back to gallery
design language·aya-quiet-metrics-interaction-states

AYA Quiet Metrics and Interaction States

A portable design language for agents: download the markdown first, then inspect the preview, tokens, and rules as needed.

Download DESIGN.md

Portable DESIGN.md source of truth for most agents and apps.

the spec

specification

philosophy
summary
AYA Quiet Metrics and Interaction States is a text-first product language for dense reading workspaces that need analytics, status, and controls without becoming a dashboard spectacle. It treats metrics as marginalia: small, legible annotations that sit beside documents, threads, and evidence clusters. The visual system translates washi restraint into modern interface behavior through warm off-white surfaces, pale ash separations, sumi text hierarchy, and highly sparse semantic pigment. State is communicated with border temperature, hairline rails, underline, opacity, and measured tint rather than with saturated card fills or glossy effects. Deep indigo is the dependable sign for focus, keyboard navigation, selection, and primary intent; low-chroma blue and green indicate information and completion; muted persimmon is saved for warnings, negative deltas, and rare moments requiring care.
values
reading focus before dashboard densitymetrics as contextual annotation rather than competing panelssurface hierarchy from tone, border, and spacing instead of shadowaccessible semantic tokens with color never acting alonequiet interaction feedback that remains visible for keyboard and pointer userscompact summaries that respect document measure and long-session calmJapanese pigment inspiration translated semantically, not ornamentally
anti-values
×glossy cards, glassmorphism, heavy shadows, and literal paper textures×saturated fills for every selected or active element×rainbow analytics palettes or arbitrary category colors×low-contrast gray text used as a substitute for hierarchy×dashboard rails that compete with the workspace context map×tiny status dots without labels, numerals, or structural cues×animations that make metrics feel live, urgent, or gamified
tokens
borders5 items
accent width
2px
character
Matte hairlines with slightly warm neutral borders; indigo outlines and rails are reserved for focus, selection, and current context.
default width
1px
focus width
2px
style
solid
colors20 items
accent
#B56A3A
background
#F7F4EE
border
#D8D0C4
border_warm
#CFC5B7
disabled
#BDB5AA
error
#9A4B42
info
#3D6F86
info_tint
#EDF4F6
muted
#6F6961
primary
#243A73
selected_tint
#EEF1F8
subtle
#9A9389
success
#5F7F63
success_tint
#EFF5ED
surface
#FFFCF6
surface_alt
#F1EEE7
surface_inset
#ECE7DE
text
#1E1B18
warning
#B56A3A
warning_tint
#FAF0E6
motion3 items
duration
120ms
easing
cubic-bezier(0.2, 0, 0, 1)
philosophy
State transitions are nearly still: opacity, border tone, underline, and 1px position changes confirm interaction without drawing attention away from reading.
radii6 items
full
9999px
lg
12px
md
8px
none
0
sm
4px
xl
16px
shadows3 items
lg
0 16px 36px rgba(30,27,24,0.06)
md
0 8px 20px rgba(30,27,24,0.045)
sm
0 1px 1px rgba(30,27,24,0.035)
spacing2 items
base
8px
scale
2, 4, 6, 8, 12, 16, 20, 24, 32, 40, 48, 64
states7 items
disabled
opacity 0.46 with preserved label contrast where content remains informative
empty
short explanatory copy, one calm outline action, optional pale ash rule or placeholder metric row
focus
2px indigo ring with 2px offset, visible around controls, chips, rows, and marginal notes
hover
increase border contrast one step; optional washi tint at 3-5 percent; reveal underline for linked metrics
loading
sumi-gray skeleton lines and tabular numeral placeholders; avoid pulsing saturated color
pressed
slightly darken border and reduce opacity to 0.92 for 80-120ms
selected
indigo 2px rail or ring plus pale indigo tint; never a fully indigo-filled card
surfaces3 items
bg pattern
No literal paper texture. If variation is needed, use a barely perceptible warm-neutral tonal field below 2 percent contrast.
card style
Flat, matte panels with 1px borders, square-to-soft radii, minimal elevation, and optional inset metric rows.
treatment
Soft-white document fields on pale ash canvas, using border temperature and spacing to separate regions.
typography8 items
base size
16px
body font
Inter
google fonts url
https://fonts.googleapis.com/css2?family=Inter:wght@400;450;500;600;700&family=IBM+Plex+Mono:wght@400;500;600&display=swap
heading font
Inter
letter spacing
-0.012em
line height
1.58
metric features
tabular-nums, slashed-zero for inline values and deltas
mono font
IBM Plex Mono
rules
accessibility
Every state must pair color with structure: border, rail, underline, icon, label, or text delta. Body text and key controls target WCAG AA on washi and ash surfaces. Focus rings must be clearly visible against all neutral and tinted states. Semantic token contrast should be verified for text uses; low-chroma tones may be used as backgrounds only when the foreground remains sumi-dark.
composition
Design screens around a dominant reading/work area with marginal analytics arranged as notes, compact summary rows, and source-aligned callouts. Use dashboards only as quiet information surfaces embedded in context: document spine, evidence clusters, recent changes, status chips, and inline metrics should orient the user without adding another panel of widgets. On wide layouts, reserve a narrow margin for metrics and status; on small screens, fold marginalia into expandable inline summaries immediately after the relevant content.
density
Default density is calm-compact: enough rows and chips for analytical work, with generous line-height and 8px rhythm to prevent fatigue. Provide density toggles that adjust row padding, metric label visibility, and marginal spacing without changing the semantic color mapping. Compact mode may hide secondary labels only when tooltips or accessible names preserve meaning.
hierarchy
Sumi text hierarchy carries the interface: strong body contrast, clear section labels, tabular numerals, and restrained weight changes. Reserve indigo for focus, current location, selected entities, and primary affordances. Reserve persimmon for warnings, negative deltas, stale data, and destructive review cues. Metrics should read as supporting punctuation, not headlines.
signature patterns
Inline metric pairs use a muted label, tabular sumi value, and a 2px semantic underline for trend or status.Marginal analytics align to content anchors with a pale ash left rule and small source/count chips, avoiding standalone dashboard cards.Status badges are outline-first: warm neutral border, low-chroma tint, text label, and optional 6px notch; no saturated pill fills.Chips use washi surfaces with border temperature changes for hover and indigo rings for keyboard focus.Selected rows or evidence clusters use an indigo left rail and pale indigo wash limited to the row interior.Loading states use quiet skeleton text lines with fixed-width numeral blocks so layout does not jump.Empty states show one sentence of orientation, one outline action, and a faint metric placeholder rather than an illustration-heavy panel.
layout
breakpoints
Mobile <= 640px stacks marginal analytics below each content anchor; tablet 641-1024px uses a primary column with collapsible insight drawer; desktop >= 1025px supports persistent document spine and marginal rail.
density
Three density modes: comfortable for long reading, balanced for default analytical work, compact for operations. Density changes vertical padding and label verbosity, not token colors or focus behavior.
grid
Reading-first 12-column desktop grid: 2-3 columns for project/document context, 6-7 columns for primary reading/workspace, 2-3 columns for marginal analytics. Gutters follow an 8px rhythm with 24px default page padding.
responsive
Chips wrap in reading order, metric groups collapse to label/value rows, and focus order follows document context before analytics so keyboard users do not get trapped in summary regions.
whitespace
Use whitespace as hierarchy: 16-24px between content groups, 8-12px inside metric clusters, and fine dividers for transitions between evidence, comments, and status.
guidance
do
  • Keep the main document or task surface visually dominant; place analytics in margins, inline summaries, or quiet context rows.
  • Use tabular numerals for percentages, counts, timestamps, confidence, and deltas.
  • Express hover, selected, pressed, and loading states through border, tint, underline, opacity, and rails.
  • Name tokens semantically while allowing pigment-inspired aliases such as sumi, washi, ai-indigo, and persimmon.
  • Use low-chroma blue and green for informative and successful states only where labels clarify meaning.
  • Provide density controls that preserve reading measure and keyboard focus visibility.
  • Test warning and delta uses of persimmon against warm surfaces for contrast and color-blind ambiguity.
avoid
  • Do not turn marginal analytics into KPI cards with large colored backgrounds.
  • Do not use literal paper fibers, ornamental Japanese motifs, or decorative texture.
  • Do not rely on dots alone for status; pair with text, notch, underline, or border.
  • Do not use saturated indigo fills for selection except for the rare primary button.
  • Do not animate metrics continuously or make loading states pulse aggressively.
  • Do not let compact density collapse line-height below comfortable reading standards.
  • Do not assign arbitrary colors to categories when neutral labels and grouping can do the job.
katagami spec
# AYA Quiet Metrics and Interaction States

## Philosophy

AYA Quiet Metrics and Interaction States is a text-first product language for dense reading workspaces that need analytics, status, and controls without becoming a dashboard spectacle. It treats metrics as marginalia: small, legible annotations that sit beside documents, threads, and evidence clusters. The visual system translates washi restraint into modern interface behavior through warm off-white surfaces, pale ash separations, sumi text hierarchy, and highly sparse semantic pigment. State is communicated with border temperature, hairline rails, underline, opacity, and measured tint rather than with saturated card fills or glossy effects. Deep indigo is the dependable sign for focus, keyboard navigation, selection, and primary intent; low-chroma blue and green indicate information and completion; muted persimmon is saved for warnings, negative deltas, and rare moments requiring care.

### Values

- reading focus before dashboard density
- metrics as contextual annotation rather than competing panels
- surface hierarchy from tone, border, and spacing instead of shadow
- accessible semantic tokens with color never acting alone
- quiet interaction feedback that remains visible for keyboard and pointer users
- compact summaries that respect document measure and long-session calm
- Japanese pigment inspiration translated semantically, not ornamentally

### Anti-Values

- glossy cards, glassmorphism, heavy shadows, and literal paper textures
- saturated fills for every selected or active element
- rainbow analytics palettes or arbitrary category colors
- low-contrast gray text used as a substitute for hierarchy
- dashboard rails that compete with the workspace context map
- tiny status dots without labels, numerals, or structural cues
- animations that make metrics feel live, urgent, or gamified

### Visual Character

- Warm white and washi surfaces sit on pale ash gutters with 1px cool-warm borders and no decorative texture.
- Inline metrics use tabular numerals, muted labels, and a small semantic rail, underline, or delta mark rather than a filled badge.
- Marginal analytics occupy narrow right-side or inline note zones, aligned to paragraphs, evidence groups, or recent-change anchors.
- Hover and pressed states change border tone, underline strength, and surface tint by one step, never by dramatic elevation.
- Selection and focus use a deep indigo ring or left hairline that remains visible in dense layouts and high-contrast review.

## Tokens

### Borders

- **Accent Width**: 2px
- **Character**: Matte hairlines with slightly warm neutral borders; indigo outlines and rails are reserved for focus, selection, and current context.
- **Default Width**: 1px
- **Focus Width**: 2px
- **Style**: solid

### Colors

| Name | Value |
|------|-------|
| accent | `#B56A3A` |
| background | `#F7F4EE` |
| border | `#D8D0C4` |
| border_warm | `#CFC5B7` |
| disabled | `#BDB5AA` |
| error | `#9A4B42` |
| info | `#3D6F86` |
| info_tint | `#EDF4F6` |
| muted | `#6F6961` |
| primary | `#243A73` |
| selected_tint | `#EEF1F8` |
| subtle | `#9A9389` |
| success | `#5F7F63` |
| success_tint | `#EFF5ED` |
| surface | `#FFFCF6` |
| surface_alt | `#F1EEE7` |
| surface_inset | `#ECE7DE` |
| text | `#1E1B18` |
| warning | `#B56A3A` |
| warning_tint | `#FAF0E6` |

### Motion

- **Duration**: 120ms
- **Easing**: cubic-bezier(0.2, 0, 0, 1)
- **Philosophy**: State transitions are nearly still: opacity, border tone, underline, and 1px position changes confirm interaction without drawing attention away from reading.

### Radii

- **Full**: 9999px
- **Lg**: 12px
- **Md**: 8px
- **None**: 0
- **Sm**: 4px
- **Xl**: 16px

### Shadows

- **Lg**: 0 16px 36px rgba(30,27,24,0.06)
- **Md**: 0 8px 20px rgba(30,27,24,0.045)
- **Sm**: 0 1px 1px rgba(30,27,24,0.035)

### Spacing

- **Base**: 8px
- **Scale**: [2,4,6,8,12,16,20,24,32,40,48,64]

### States

- **Disabled**: opacity 0.46 with preserved label contrast where content remains informative
- **Empty**: short explanatory copy, one calm outline action, optional pale ash rule or placeholder metric row
- **Focus**: 2px indigo ring with 2px offset, visible around controls, chips, rows, and marginal notes
- **Hover**: increase border contrast one step; optional washi tint at 3-5 percent; reveal underline for linked metrics
- **Loading**: sumi-gray skeleton lines and tabular numeral placeholders; avoid pulsing saturated color
- **Pressed**: slightly darken border and reduce opacity to 0.92 for 80-120ms
- **Selected**: indigo 2px rail or ring plus pale indigo tint; never a fully indigo-filled card

### Surfaces

- **Bg Pattern**: No literal paper texture. If variation is needed, use a barely perceptible warm-neutral tonal field below 2 percent contrast.
- **Card Style**: Flat, matte panels with 1px borders, square-to-soft radii, minimal elevation, and optional inset metric rows.
- **Treatment**: Soft-white document fields on pale ash canvas, using border temperature and spacing to separate regions.

### Typography

- **Base Size**: 16px
- **Body Font**: Inter
- **Google Fonts Url**: https://fonts.googleapis.com/css2?family=Inter:wght@400;450;500;600;700&family=IBM+Plex+Mono:wght@400;500;600&display=swap
- **Heading Font**: Inter
- **Letter Spacing**: -0.012em
- **Line Height**: 1.58
- **Metric Features**: tabular-nums, slashed-zero for inline values and deltas
- **Mono Font**: IBM Plex Mono

## Rules

### Accessibility

Every state must pair color with structure: border, rail, underline, icon, label, or text delta. Body text and key controls target WCAG AA on washi and ash surfaces. Focus rings must be clearly visible against all neutral and tinted states. Semantic token contrast should be verified for text uses; low-chroma tones may be used as backgrounds only when the foreground remains sumi-dark.

### Composition

Design screens around a dominant reading/work area with marginal analytics arranged as notes, compact summary rows, and source-aligned callouts. Use dashboards only as quiet information surfaces embedded in context: document spine, evidence clusters, recent changes, status chips, and inline metrics should orient the user without adding another panel of widgets. On wide layouts, reserve a narrow margin for metrics and status; on small screens, fold marginalia into expandable inline summaries immediately after the relevant content.

### Density

Default density is calm-compact: enough rows and chips for analytical work, with generous line-height and 8px rhythm to prevent fatigue. Provide density toggles that adjust row padding, metric label visibility, and marginal spacing without changing the semantic color mapping. Compact mode may hide secondary labels only when tooltips or accessible names preserve meaning.

### Hierarchy

Sumi text hierarchy carries the interface: strong body contrast, clear section labels, tabular numerals, and restrained weight changes. Reserve indigo for focus, current location, selected entities, and primary affordances. Reserve persimmon for warnings, negative deltas, stale data, and destructive review cues. Metrics should read as supporting punctuation, not headlines.

### Signature Patterns

- Inline metric pairs use a muted label, tabular sumi value, and a 2px semantic underline for trend or status.
- Marginal analytics align to content anchors with a pale ash left rule and small source/count chips, avoiding standalone dashboard cards.
- Status badges are outline-first: warm neutral border, low-chroma tint, text label, and optional 6px notch; no saturated pill fills.
- Chips use washi surfaces with border temperature changes for hover and indigo rings for keyboard focus.
- Selected rows or evidence clusters use an indigo left rail and pale indigo wash limited to the row interior.
- Loading states use quiet skeleton text lines with fixed-width numeral blocks so layout does not jump.
- Empty states show one sentence of orientation, one outline action, and a faint metric placeholder rather than an illustration-heavy panel.

## Layout

### Breakpoints

Mobile <= 640px stacks marginal analytics below each content anchor; tablet 641-1024px uses a primary column with collapsible insight drawer; desktop >= 1025px supports persistent document spine and marginal rail.

### Density

Three density modes: comfortable for long reading, balanced for default analytical work, compact for operations. Density changes vertical padding and label verbosity, not token colors or focus behavior.

### Grid

Reading-first 12-column desktop grid: 2-3 columns for project/document context, 6-7 columns for primary reading/workspace, 2-3 columns for marginal analytics. Gutters follow an 8px rhythm with 24px default page padding.

### Responsive

Chips wrap in reading order, metric groups collapse to label/value rows, and focus order follows document context before analytics so keyboard users do not get trapped in summary regions.

### Whitespace

Use whitespace as hierarchy: 16-24px between content groups, 8-12px inside metric clusters, and fine dividers for transitions between evidence, comments, and status.

## Guidance

### Do

- Keep the main document or task surface visually dominant; place analytics in margins, inline summaries, or quiet context rows.
- Use tabular numerals for percentages, counts, timestamps, confidence, and deltas.
- Express hover, selected, pressed, and loading states through border, tint, underline, opacity, and rails.
- Name tokens semantically while allowing pigment-inspired aliases such as sumi, washi, ai-indigo, and persimmon.
- Use low-chroma blue and green for informative and successful states only where labels clarify meaning.
- Provide density controls that preserve reading measure and keyboard focus visibility.
- Test warning and delta uses of persimmon against warm surfaces for contrast and color-blind ambiguity.

### Don't

- Do not turn marginal analytics into KPI cards with large colored backgrounds.
- Do not use literal paper fibers, ornamental Japanese motifs, or decorative texture.
- Do not rely on dots alone for status; pair with text, notch, underline, or border.
- Do not use saturated indigo fills for selection except for the rare primary button.
- Do not animate metrics continuously or make loading states pulse aggressively.
- Do not let compact density collapse line-height below comfortable reading standards.
- Do not assign arbitrary colors to categories when neutral labels and grouping can do the job.

### Accessibility

Use structural state cues in addition to color. Indigo focus rings are mandatory and should not be removed in mouse mode. Keep muted text above accessible contrast; reserve low-contrast tones for dividers, not essential labels.

### Usage Context

Best for AI workspaces, document review tools, research products, editorial analytics, source-tracking systems, operational notes, and any dense application where metrics must support comprehension without stealing attention.
DESIGN.md
---
version: "alpha"
name: "AYA Quiet Metrics and Interaction States"
description: "Agent-curated design language exported from Katagami as DESIGN.md."
colors:
  accent: "#B56A3A"
  background: "#F7F4EE"
  border: "#D8D0C4"
  border_warm: "#CFC5B7"
  disabled: "#BDB5AA"
  error: "#9A4B42"
  info: "#3D6F86"
  info_tint: "#EDF4F6"
  muted: "#6F6961"
  primary: "#243A73"
  selected_tint: "#EEF1F8"
  subtle: "#9A9389"
  success: "#5F7F63"
  success_tint: "#EFF5ED"
  surface: "#FFFCF6"
  surface_alt: "#F1EEE7"
  surface_inset: "#ECE7DE"
  text: "#1E1B18"
  warning: "#B56A3A"
  warning_tint: "#FAF0E6"
typography:
  headline-lg:
    fontFamily: "Inter"
    fontSize: "1.953rem"
    fontWeight: 700
    lineHeight: 1.1
    letterSpacing: "-0.012em"
  headline-md:
    fontFamily: "Inter"
    fontSize: "1.563rem"
    fontWeight: 600
    lineHeight: 1.15
    letterSpacing: "-0.012em"
  body-md:
    fontFamily: "Inter"
    fontSize: "16px"
    fontWeight: 400
    lineHeight: 1.58
    letterSpacing: "-0.012em"
  label-md:
    fontFamily: "IBM Plex Mono"
    fontSize: "0.75rem"
    fontWeight: 600
    lineHeight: 1
    letterSpacing: "0.08em"
rounded:
  full: "9999px"
  lg: "12px"
  md: "8px"
  none: "0px"
  sm: "4px"
  xl: "16px"
spacing:
  base: "8px"
  xs: "2px"
  sm: "4px"
  md: "6px"
  lg: "8px"
  xl: "12px"
  2xl: "16px"
  3xl: "20px"
  4xl: "24px"
  step-8: "32px"
  step-9: "40px"
  step-10: "48px"
  step-11: "64px"
components:
  color-reference-accent:
    backgroundColor: "{colors.accent}"
  color-reference-background:
    backgroundColor: "{colors.background}"
  color-reference-border:
    backgroundColor: "{colors.border}"
  color-reference-border_warm:
    backgroundColor: "{colors.border_warm}"
  color-reference-disabled:
    backgroundColor: "{colors.disabled}"
  color-reference-error:
    backgroundColor: "{colors.error}"
  color-reference-info:
    backgroundColor: "{colors.info}"
  color-reference-info_tint:
    backgroundColor: "{colors.info_tint}"
  color-reference-muted:
    backgroundColor: "{colors.muted}"
  color-reference-primary:
    backgroundColor: "{colors.primary}"
  color-reference-selected_tint:
    backgroundColor: "{colors.selected_tint}"
  color-reference-subtle:
    backgroundColor: "{colors.subtle}"
  color-reference-success:
    backgroundColor: "{colors.success}"
  color-reference-success_tint:
    backgroundColor: "{colors.success_tint}"
  color-reference-surface:
    backgroundColor: "{colors.surface}"
  color-reference-surface_alt:
    backgroundColor: "{colors.surface_alt}"
  color-reference-surface_inset:
    backgroundColor: "{colors.surface_inset}"
  color-reference-text:
    backgroundColor: "{colors.text}"
  color-reference-warning:
    backgroundColor: "{colors.warning}"
  color-reference-warning_tint:
    backgroundColor: "{colors.warning_tint}"
  button-primary:
    backgroundColor: "{colors.primary}"
    textColor: "#ffffff"
    typography: "{typography.label-md}"
    rounded: "{rounded.md}"
    padding: "{spacing.md}"
  card-surface:
    backgroundColor: "{colors.surface}"
    textColor: "{colors.text}"
    rounded: "{rounded.md}"
    padding: "{spacing.md}"
  input-default:
    backgroundColor: "{colors.surface}"
    textColor: "{colors.text}"
    rounded: "{rounded.md}"
    height: "44px"
---

# AYA Quiet Metrics and Interaction States

## Overview

AYA Quiet Metrics and Interaction States is a text-first product language for dense reading workspaces that need analytics, status, and controls without becoming a dashboard spectacle. It treats metrics as marginalia: small, legible annotations that sit beside documents, threads, and evidence clusters. The visual system translates washi restraint into modern interface behavior through warm off-white surfaces, pale ash separations, sumi text hierarchy, and highly sparse semantic pigment. State is communicated with border temperature, hairline rails, underline, opacity, and measured tint rather than with saturated card fills or glossy effects. Deep indigo is the dependable sign for focus, keyboard navigation, selection, and primary intent; low-chroma blue and green indicate information and completion; muted persimmon is saved for warnings, negative deltas, and rare moments requiring care.

### Values

- reading focus before dashboard density
- metrics as contextual annotation rather than competing panels
- surface hierarchy from tone, border, and spacing instead of shadow
- accessible semantic tokens with color never acting alone
- quiet interaction feedback that remains visible for keyboard and pointer users
- compact summaries that respect document measure and long-session calm
- Japanese pigment inspiration translated semantically, not ornamentally

### Anti-Values

- glossy cards, glassmorphism, heavy shadows, and literal paper textures
- saturated fills for every selected or active element
- rainbow analytics palettes or arbitrary category colors
- low-contrast gray text used as a substitute for hierarchy
- dashboard rails that compete with the workspace context map
- tiny status dots without labels, numerals, or structural cues
- animations that make metrics feel live, urgent, or gamified

### Visual Character

- Warm white and washi surfaces sit on pale ash gutters with 1px cool-warm borders and no decorative texture.
- Inline metrics use tabular numerals, muted labels, and a small semantic rail, underline, or delta mark rather than a filled badge.
- Marginal analytics occupy narrow right-side or inline note zones, aligned to paragraphs, evidence groups, or recent-change anchors.
- Hover and pressed states change border tone, underline strength, and surface tint by one step, never by dramatic elevation.
- Selection and focus use a deep indigo ring or left hairline that remains visible in dense layouts and high-contrast review.

## Colors

Use the YAML color tokens as the normative palette. The prose below names the roles agents should preserve when generating UI.

| Token | Value |
|-------|-------|
| accent | `#B56A3A` |
| background | `#F7F4EE` |
| border | `#D8D0C4` |
| border_warm | `#CFC5B7` |
| disabled | `#BDB5AA` |
| error | `#9A4B42` |
| info | `#3D6F86` |
| info_tint | `#EDF4F6` |
| muted | `#6F6961` |
| primary | `#243A73` |
| selected_tint | `#EEF1F8` |
| subtle | `#9A9389` |
| success | `#5F7F63` |
| success_tint | `#EFF5ED` |
| surface | `#FFFCF6` |
| surface_alt | `#F1EEE7` |
| surface_inset | `#ECE7DE` |
| text | `#1E1B18` |
| warning | `#B56A3A` |
| warning_tint | `#FAF0E6` |

## Typography

- **Headline-Lg**: Inter, 1.953rem, weight 700, line-height 1.1.
- **Headline-Md**: Inter, 1.563rem, weight 600, line-height 1.15.
- **Body-Md**: Inter, 16px, weight 400, line-height 1.58.
- **Label-Md**: IBM Plex Mono, 0.75rem, weight 600, line-height 1.

## Layout

### Spacing Tokens

- **Base**: `8px`
- **Xs**: `2px`
- **Sm**: `4px`
- **Md**: `6px`
- **Lg**: `8px`
- **Xl**: `12px`
- **2xl**: `16px`
- **3xl**: `20px`
- **4xl**: `24px`
- **Step-8**: `32px`
- **Step-9**: `40px`
- **Step-10**: `48px`
- **Step-11**: `64px`

### Breakpoints

Mobile <= 640px stacks marginal analytics below each content anchor; tablet 641-1024px uses a primary column with collapsible insight drawer; desktop >= 1025px supports persistent document spine and marginal rail.

### Density

Three density modes: comfortable for long reading, balanced for default analytical work, compact for operations. Density changes vertical padding and label verbosity, not token colors or focus behavior.

### Grid

Reading-first 12-column desktop grid: 2-3 columns for project/document context, 6-7 columns for primary reading/workspace, 2-3 columns for marginal analytics. Gutters follow an 8px rhythm with 24px default page padding.

### Responsive

Chips wrap in reading order, metric groups collapse to label/value rows, and focus order follows document context before analytics so keyboard users do not get trapped in summary regions.

### Whitespace

Use whitespace as hierarchy: 16-24px between content groups, 8-12px inside metric clusters, and fine dividers for transitions between evidence, comments, and status.

## Elevation & Depth

### Shadows

- **Lg**: 0 16px 36px rgba(30,27,24,0.06)
- **Md**: 0 8px 20px rgba(30,27,24,0.045)
- **Sm**: 0 1px 1px rgba(30,27,24,0.035)

## Shapes

### Rounded

- **Full**: `9999px`
- **Lg**: `12px`
- **Md**: `8px`
- **None**: `0px`
- **Sm**: `4px`
- **Xl**: `16px`

### Surfaces

- **Bg Pattern**: No literal paper texture. If variation is needed, use a barely perceptible warm-neutral tonal field below 2 percent contrast.
- **Card Style**: Flat, matte panels with 1px borders, square-to-soft radii, minimal elevation, and optional inset metric rows.
- **Treatment**: Soft-white document fields on pale ash canvas, using border temperature and spacing to separate regions.

### Borders

- **Accent Width**: 2px
- **Character**: Matte hairlines with slightly warm neutral borders; indigo outlines and rails are reserved for focus, selection, and current context.
- **Default Width**: 1px
- **Focus Width**: 2px
- **Style**: solid

## Components

### Accessibility

Every state must pair color with structure: border, rail, underline, icon, label, or text delta. Body text and key controls target WCAG AA on washi and ash surfaces. Focus rings must be clearly visible against all neutral and tinted states. Semantic token contrast should be verified for text uses; low-chroma tones may be used as backgrounds only when the foreground remains sumi-dark.

### Composition

Design screens around a dominant reading/work area with marginal analytics arranged as notes, compact summary rows, and source-aligned callouts. Use dashboards only as quiet information surfaces embedded in context: document spine, evidence clusters, recent changes, status chips, and inline metrics should orient the user without adding another panel of widgets. On wide layouts, reserve a narrow margin for metrics and status; on small screens, fold marginalia into expandable inline summaries immediately after the relevant content.

### Density

Default density is calm-compact: enough rows and chips for analytical work, with generous line-height and 8px rhythm to prevent fatigue. Provide density toggles that adjust row padding, metric label visibility, and marginal spacing without changing the semantic color mapping. Compact mode may hide secondary labels only when tooltips or accessible names preserve meaning.

### Hierarchy

Sumi text hierarchy carries the interface: strong body contrast, clear section labels, tabular numerals, and restrained weight changes. Reserve indigo for focus, current location, selected entities, and primary affordances. Reserve persimmon for warnings, negative deltas, stale data, and destructive review cues. Metrics should read as supporting punctuation, not headlines.

### Signature Patterns

- Inline metric pairs use a muted label, tabular sumi value, and a 2px semantic underline for trend or status.
- Marginal analytics align to content anchors with a pale ash left rule and small source/count chips, avoiding standalone dashboard cards.
- Status badges are outline-first: warm neutral border, low-chroma tint, text label, and optional 6px notch; no saturated pill fills.
- Chips use washi surfaces with border temperature changes for hover and indigo rings for keyboard focus.
- Selected rows or evidence clusters use an indigo left rail and pale indigo wash limited to the row interior.
- Loading states use quiet skeleton text lines with fixed-width numeral blocks so layout does not jump.
- Empty states show one sentence of orientation, one outline action, and a faint metric placeholder rather than an illustration-heavy panel.

## shadcn/ui Usage

When the target app uses shadcn/ui, copy DESIGN.md with shadcn instead of the plain DESIGN.md. It contains the same Katagami design-language source plus the shadcn/ui primitives, imports, theme variables, component recipes, and preview-shot guidance.

DESIGN.md with shadcn: `/language/aya-quiet-metrics-interaction-states/DESIGN.with-shadcn.md`.

The shadcn page also exposes optional machine-readable files for automation, but the human-facing handoff is DESIGN.md with shadcn.

Install recommended primitives with `npx shadcn@latest add button card input textarea select dialog sheet tabs badge separator checkbox switch slider tooltip dropdown-menu table`.

Use these primitives in shadcn apps:
- button
- card
- input
- textarea
- select
- dialog
- sheet
- tabs
- badge
- separator
- checkbox
- switch
- slider
- tooltip
- dropdown-menu
- table

Implementation rule for agents: import shadcn primitives from `@/components/ui/*`, apply the generated CSS variables first, then compose the language-specific recipes from the companion MD. Katagami remains the source of truth; shadcn names are the implementation surface.

## Do's and Don'ts

- Do Keep the main document or task surface visually dominant; place analytics in margins, inline summaries, or quiet context rows.
- Do Use tabular numerals for percentages, counts, timestamps, confidence, and deltas.
- Do Express hover, selected, pressed, and loading states through border, tint, underline, opacity, and rails.
- Do Name tokens semantically while allowing pigment-inspired aliases such as sumi, washi, ai-indigo, and persimmon.
- Do Use low-chroma blue and green for informative and successful states only where labels clarify meaning.
- Do Provide density controls that preserve reading measure and keyboard focus visibility.
- Do Test warning and delta uses of persimmon against warm surfaces for contrast and color-blind ambiguity.
- Don't Do not turn marginal analytics into KPI cards with large colored backgrounds.
- Don't Do not use literal paper fibers, ornamental Japanese motifs, or decorative texture.
- Don't Do not rely on dots alone for status; pair with text, notch, underline, or border.
- Don't Do not use saturated indigo fills for selection except for the rare primary button.
- Don't Do not animate metrics continuously or make loading states pulse aggressively.
- Don't Do not let compact density collapse line-height below comfortable reading standards.
- Don't Do not assign arbitrary colors to categories when neutral labels and grouping can do the job.

### Accessibility

Use structural state cues in addition to color. Indigo focus rings are mandatory and should not be removed in mouse mode. Keep muted text above accessible contrast; reserve low-contrast tones for dividers, not essential labels.

### Usage Context

Best for AI workspaces, document review tools, research products, editorial analytics, source-tracking systems, operational notes, and any dense application where metrics must support comprehension without stealing attention.
shadcn/ui theme
```json
{
  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
  "name": "aya-quiet-metrics-interaction-states",
  "type": "registry:theme",
  "title": "AYA Quiet Metrics and Interaction States shadcn Theme",
  "cssVars": {
    "theme": {},
    "light": {
      "background": "#F7F4EE",
      "foreground": "#1E1B18",
      "card": "#FFFCF6",
      "card-foreground": "#1E1B18",
      "popover": "#FFFCF6",
      "popover-foreground": "#1E1B18",
      "primary": "#243A73",
      "primary-foreground": "#ffffff",
      "secondary": "#f4f4f5",
      "secondary-foreground": "#111111",
      "muted": "#6F6961",
      "muted-foreground": "#1E1B18",
      "accent": "#B56A3A",
      "accent-foreground": "#ffffff",
      "destructive": "#9A4B42",
      "border": "#D8D0C4",
      "input": "#D8D0C4",
      "ring": "#B56A3A",
      "chart-1": "#243A73",
      "chart-2": "#f4f4f5",
      "chart-3": "#B56A3A",
      "chart-4": "#5F7F63",
      "chart-5": "#B56A3A",
      "sidebar": "#FFFCF6",
      "sidebar-foreground": "#1E1B18",
      "sidebar-primary": "#243A73",
      "sidebar-primary-foreground": "#ffffff",
      "sidebar-accent": "#3D6F86",
      "sidebar-accent-foreground": "#ffffff",
      "sidebar-border": "#D8D0C4",
      "sidebar-ring": "#B56A3A",
      "radius": "8px"
    },
    "dark": {
      "background": "#0f1115",
      "foreground": "#f8fafc",
      "card": "#181b22",
      "card-foreground": "#f8fafc",
      "popover": "#181b22",
      "popover-foreground": "#f8fafc",
      "primary": "#243A73",
      "primary-foreground": "#ffffff",
      "secondary": "#252a33",
      "secondary-foreground": "#f8fafc",
      "muted": "#252a33",
      "muted-foreground": "#a1a1aa",
      "accent": "#B56A3A",
      "accent-foreground": "#ffffff",
      "destructive": "#9A4B42",
      "border": "#303642",
      "input": "#303642",
      "ring": "#B56A3A",
      "chart-1": "#243A73",
      "chart-2": "#f4f4f5",
      "chart-3": "#B56A3A",
      "chart-4": "#5F7F63",
      "chart-5": "#B56A3A",
      "sidebar": "#181b22",
      "sidebar-foreground": "#f8fafc",
      "sidebar-primary": "#243A73",
      "sidebar-primary-foreground": "#ffffff",
      "sidebar-accent": "#B56A3A",
      "sidebar-accent-foreground": "#ffffff",
      "sidebar-border": "#303642",
      "sidebar-ring": "#B56A3A",
      "radius": "8px"
    }
  },
  "meta": {
    "source": "katagami",
    "languageId": "aya-quiet-metrics-interaction-states",
    "slug": "aya-quiet-metrics-interaction-states",
    "componentManifest": [
      "button",
      "card",
      "input",
      "textarea",
      "select",
      "dialog",
      "sheet",
      "tabs",
      "badge",
      "separator",
      "checkbox",
      "switch",
      "slider",
      "tooltip",
      "dropdown-menu",
      "table"
    ],
    "installCommand": "npx shadcn@latest add button card input textarea select dialog sheet tabs badge separator checkbox switch slider tooltip dropdown-menu table",
    "nativeTokenNames": {
      "borders": [
        "accent_width",
        "character",
        "default_width",
        "focus_width",
        "style"
      ],
      "colors": [
        "accent",
        "background",
        "border",
        "border_warm",
        "disabled",
        "error",
        "info",
        "info_tint",
        "muted",
        "primary",
        "selected_tint",
        "subtle",
        "success",
        "success_tint",
        "surface",
        "surface_alt",
        "surface_inset",
        "text",
        "warning",
        "warning_tint"
      ],
      "motion": [
        "duration",
        "easing",
        "philosophy"
      ],
      "radii": [
        "full",
        "lg",
        "md",
        "none",
        "sm",
        "xl"
      ],
      "shadows": [
        "lg",
        "md",
        "sm"
      ],
      "spacing": [
        "base",
        "scale"
      ],
      "states": [
        "disabled",
        "empty",
        "focus",
        "hover",
        "loading",
        "pressed",
        "selected"
      ],
      "surfaces": [
        "bg_pattern",
        "card_style",
        "treatment"
      ],
      "typography": [
        "base_size",
        "body_font",
        "google_fonts_url",
        "heading_font",
        "letter_spacing",
        "line_height",
        "metric_features",
        "mono_font"
      ]
    }
  }
}
```
in the wild

embodiments

Design Language Preview

AYA Quiet Metrics and Interaction States

Color Palette

primary
secondary
accent
background
surface
text
muted
border
error
success
warning
info

Typography

h1

Heading One

h2

Heading Two

h3

Heading Three

h4

Heading Four

body

Body text demonstrates the reading experience. Good typography is invisible — it lets the content speak without drawing attention to the letterforms themselves.

caption

Caption text for supplementary information and metadata.

code
const theme = applyTokens(designLanguage);
render(<App theme={theme} />);

Buttons

Form Controls

Navigation

tabs
Overview content area with contextual information about the design language.
segmented control
dropdown menu

Feedback & Status

badges
NewDefaultActivePendingErrorOutline
alerts
Info: A new version is available.
Success: Changes saved successfully.
Warning: Storage is almost full.
Error: Failed to process request.
progress
66% complete
tooltip
avatar
AKJDML

Containers & Overlays

card

Card Title

Cards group related content and actions. This example shows a basic content card with a title and description.

accordion

Design tokens are the atomic values of a design system — colors, spacing, typography, and other values stored as key-value pairs.

dialog
separator

Data Display

table
NameStatusCategoryScore
Neo BrutalismPublishedMaximalist94
Aero GlassDraftSpatial87
Signal UIReviewEnterprise91
stat cards
Languages
42
+12%
Elements
3,150
+8%
Usage
18.4k
+23%
DESIGN.md

at a glance

Palette

Typography

headline-lgInter · 31px · 700

The quick brown fox jumps

headline-mdInter · 25px · 600

The quick brown fox jumps

body-mdInter · 16px · 400

The quick brown fox jumps

label-mdIBM Plex Mono · 12px · 600

The quick brown fox jumps

Components

New
Card title

Components rendered with this language’s tokens — colors, type, and rounded corners as specified.

Spacing

  • base8px
  • xs2px
  • sm4px
  • md6px
  • lg8px
  • xl12px
  • 2xl16px
  • 3xl20px
  • 4xl24px
  • step-832px
  • step-940px
  • step-1048px
  • step-1164px

Shape

full9999px
lg12px
md8px
none0px
sm4px
xl16px
shadcn/ui

implementation kit

needs agent-authored kitcompatibility fallback
shadcn compatibility only
The generated theme variables are available, but the polished shadcn component recipes and shots have not been authored by the Katagami agent yet.
fallbackprimitives render
Compatibility proof
Local shadcn-style primitives accept the generated theme variables.
primaryaccentsurfacemutederror
table rhythm
buttonok
cardok
inputok
recommendedcompatibility fallback

DESIGN.md with shadcn

Copy this when the target app uses shadcn/ui. It packages the Katagami DESIGN.md context with the install list, theme variables, component recipes, preview-shot contract, and starter TSX in one Markdown companion.

advanced implementation filesoptional machine-readable theme, CSS, TSX starter, recipes, and preview contract
shadcn add
npx shadcn@latest add button card input textarea select dialog sheet tabs badge separator checkbox switch slider tooltip dropdown-menu table
theme css
:root {
  --background: #F7F4EE;
  --foreground: #1E1B18;
  --card: #FFFCF6;
  --card-foreground: #1E1B18;
  --popover: #FFFCF6;
  --popover-foreground: #1E1B18;
  --primary: #243A73;
  --primary-foreground: #ffffff;
  --secondary: #f4f4f5;
  --secondary-foreground: #111111;
  --muted: #6F6961;
  --muted-foreground: #1E1B18;
  --accent: #B56A3A;
  --accent-foreground: #ffffff;
  --destructive: #9A4B42;
  --border: #D8D0C4;
  --input: #D8D0C4;
  --ring: #B56A3A;
  --chart-1: #243A73;
  --chart-2: #f4f4f5;
  --chart-3: #B56A3A;
  --chart-4: #5F7F63;
  --chart-5: #B56A3A;
  --sidebar: #FFFCF6;
  --sidebar-foreground: #1E1B18;
  --sidebar-primary: #243A73;
  --sidebar-primary-foreground: #ffffff;
  --sidebar-accent: #3D6F86;
  --sidebar-accent-foreground: #ffffff;
  --sidebar-border: #D8D0C4;
  --sidebar-ring: #B56A3A;
  --radius: 8px;
}

.dark {
  --background: #0f1115;
  --foreground: #f8fafc;
  --card: #181b22;
  --card-foreground: #f8fafc;
  --popover: #181b22;
  --popover-foreground: #f8fafc;
  --primary: #243A73;
  --primary-foreground: #ffffff;
  --secondary: #252a33;
  --secondary-foreground: #f8fafc;
  --muted: #252a33;
  --muted-foreground: #a1a1aa;
  --accent: #B56A3A;
  --accent-foreground: #ffffff;
  --destructive: #9A4B42;
  --border: #303642;
  --input: #303642;
  --ring: #B56A3A;
  --chart-1: #243A73;
  --chart-2: #f4f4f5;
  --chart-3: #B56A3A;
  --chart-4: #5F7F63;
  --chart-5: #B56A3A;
  --sidebar: #181b22;
  --sidebar-foreground: #f8fafc;
  --sidebar-primary: #243A73;
  --sidebar-primary-foreground: #ffffff;
  --sidebar-accent: #B56A3A;
  --sidebar-accent-foreground: #ffffff;
  --sidebar-border: #303642;
  --sidebar-ring: #B56A3A;
  --radius: 8px;
}
tsx starter
import { Badge } from "@/components/ui/badge";
import { Button } from "@/components/ui/button";
import {
  Card,
  CardContent,
  CardDescription,
  CardFooter,
  CardHeader,
  CardTitle,
} from "@/components/ui/card";
import { Input } from "@/components/ui/input";
import { Tabs, TabsList, TabsTrigger } from "@/components/ui/tabs";

export function AyaQuietMetricsAndInteractionStatesShadcnKit() {
  return (
    <section className="grid gap-4 rounded-[var(--radius)] border bg-background p-4 text-foreground">
      <div className="flex items-start justify-between gap-4">
        <div>
          <Badge variant="outline">shadcn/ui</Badge>
          <h2 className="mt-3 text-2xl font-semibold tracking-tight">AYA Quiet Metrics and Interaction States</h2>
          <p className="mt-1 max-w-xl text-sm text-muted-foreground">
            Use the Katagami registry theme, then compose these shadcn primitives
            with the language-specific component recipes.
          </p>
        </div>
        <Button>Apply theme</Button>
      </div>

      <Tabs defaultValue="components">
        <TabsList>
          <TabsTrigger value="components">Components</TabsTrigger>
          <TabsTrigger value="states">States</TabsTrigger>
          <TabsTrigger value="export">Export</TabsTrigger>
        </TabsList>
      </Tabs>

      <Card>
        <CardHeader>
          <CardTitle>Component recipe</CardTitle>
          <CardDescription>
            Replace this starter content with the agent-authored product scene
            from components.md and preview-shots.json.
          </CardDescription>
        </CardHeader>
        <CardContent className="grid gap-3 sm:grid-cols-[1fr_auto]">
          <Input defaultValue="Tokenized shadcn surface" aria-label="Recipe name" />
          <Button variant="secondary">Preview state</Button>
        </CardContent>
        <CardFooter className="justify-between">
          <Badge>Ready</Badge>
          <Button variant="outline">Copy recipe</Button>
        </CardFooter>
      </Card>
    </section>
  );
}
theme JSONcompatibility fallback
{
  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
  "name": "aya-quiet-metrics-interaction-states",
  "type": "registry:theme",
  "title": "AYA Quiet Metrics and Interaction States shadcn Theme",
  "cssVars": {
    "theme": {},
    "light": {
      "background": "#F7F4EE",
      "foreground": "#1E1B18",
      "card": "#FFFCF6",
      "card-foreground": "#1E1B18",
      "popover": "#FFFCF6",
      "popover-foreground": "#1E1B18",
      "primary": "#243A73",
      "primary-foreground": "#ffffff",
      "secondary": "#f4f4f5",
      "secondary-foreground": "#111111",
      "muted": "#6F6961",
      "muted-foreground": "#1E1B18",
      "accent": "#B56A3A",
      "accent-foreground": "#ffffff",
      "destructive": "#9A4B42",
      "border": "#D8D0C4",
      "input": "#D8D0C4",
      "ring": "#B56A3A",
      "chart-1": "#243A73",
      "chart-2": "#f4f4f5",
      "chart-3": "#B56A3A",
      "chart-4": "#5F7F63",
      "chart-5": "#B56A3A",
      "sidebar": "#FFFCF6",
      "sidebar-foreground": "#1E1B18",
      "sidebar-primary": "#243A73",
      "sidebar-primary-foreground": "#ffffff",
      "sidebar-accent": "#3D6F86",
      "sidebar-accent-foreground": "#ffffff",
      "sidebar-border": "#D8D0C4",
      "sidebar-ring": "#B56A3A",
      "radius": "8px"
    },
    "dark": {
      "background": "#0f1115",
      "foreground": "#f8fafc",
      "card": "#181b22",
      "card-foreground": "#f8fafc",
      "popover": "#181b22",
      "popover-foreground": "#f8fafc",
      "primary": "#243A73",
      "primary-foreground": "#ffffff",
      "secondary": "#252a33",
      "secondary-foreground": "#f8fafc",
      "muted": "#252a33",
      "muted-foreground": "#a1a1aa",
      "accent": "#B56A3A",
      "accent-foreground": "#ffffff",
      "destructive": "#9A4B42",
      "border": "#303642",
      "input": "#303642",
      "ring": "#B56A3A",
      "chart-1": "#243A73",
      "chart-2": "#f4f4f5",
      "chart-3": "#B56A3A",
      "chart-4": "#5F7F63",
      "chart-5": "#B56A3A",
      "sidebar": "#181b22",
      "sidebar-foreground": "#f8fafc",
      "sidebar-primary": "#243A73",
      "sidebar-primary-foreground": "#ffffff",
      "sidebar-accent": "#B56A3A",
      "sidebar-accent-foreground": "#ffffff",
      "sidebar-border": "#303642",
      "sidebar-ring": "#B56A3A",
      "radius": "8px"
    }
  },
  "meta": {
    "source": "katagami",
    "languageId": "aya-quiet-metrics-interaction-states",
    "slug": "aya-quiet-metrics-interaction-states",
    "componentManifest": [
      "button",
      "card",
      "input",
      "textarea",
      "select",
      "dialog",
      "sheet",
      "tabs",
      "badge",
      "separator",
      "checkbox",
      "switch",
      "slider",
      "tooltip",
      "dropdown-menu",
      "table"
    ],
    "installCommand": "npx shadcn@latest add button card input textarea select dialog sheet tabs badge separator checkbox switch slider tooltip dropdown-menu table",
    "nativeTokenNames": {
      "borders": [
        "accent_width",
        "character",
        "default_width",
        "focus_width",
        "style"
      ],
      "colors": [
        "accent",
        "background",
        "border",
        "border_warm",
        "disabled",
        "error",
        "info",
        "info_tint",
        "muted",
        "primary",
        "selected_tint",
        "subtle",
        "success",
        "success_tint",
        "surface",
        "surface_alt",
        "surface_inset",
        "text",
        "warning",
        "warning_tint"
      ],
      "motion": [
        "duration",
        "easing",
        "philosophy"
      ],
      "radii": [
        "full",
        "lg",
        "md",
        "none",
        "sm",
        "xl"
      ],
      "shadows": [
        "lg",
        "md",
        "sm"
      ],
      "spacing": [
        "base",
        "scale"
      ],
      "states": [
        "disabled",
        "empty",
        "focus",
        "hover",
        "loading",
        "pressed",
        "selected"
      ],
      "surfaces": [
        "bg_pattern",
        "card_style",
        "treatment"
      ],
      "typography": [
        "base_size",
        "body_font",
        "google_fonts_url",
        "heading_font",
        "letter_spacing",
        "line_height",
        "metric_features",
        "mono_font"
      ]
    }
  }
}
component recipescompatibility fallback
# AYA Quiet Metrics and Interaction States shadcn/ui Components

Artifact: `component-recipes-v1`
Author: `katagami-ui-projection`
Language ID: `aya-quiet-metrics-interaction-states`
Slug: `aya-quiet-metrics-interaction-states`

## Intent

AYA Quiet Metrics and Interaction States is a text-first product language for dense reading workspaces that need analytics, status, and controls without becoming a dashboard spectacle. It treats metrics as marginalia: small, legible annotations that sit beside documents, threads, and evidence clusters. The visual system translates washi restraint into modern interface behavior through warm off-white surfaces, pale ash separations, sumi text hierarchy, and highly sparse semantic pigment. State is communicated with border temperature, hairline rails, underline, opacity, and measured tint rather than with saturated card fills or glossy effects. Deep indigo is the dependable sign for focus, keyboard navigation, selection, and primary intent; low-chroma blue and green indicate information and completion; muted persimmon is saved for warnings, negative deltas, and rare moments requiring care.

## Required primitives

- button
- card
- input
- textarea
- select
- dialog
- sheet
- tabs
- badge
- separator
- checkbox
- switch
- slider
- tooltip
- dropdown-menu
- table

Install with `npx shadcn@latest add button card input textarea select dialog sheet tabs badge separator checkbox switch slider tooltip dropdown-menu table`.

## Token cues

Colors:

{
  "accent": "#B56A3A",
  "background": "#F7F4EE",
  "border": "#D8D0C4",
  "border_warm": "#CFC5B7",
  "disabled": "#BDB5AA",
  "error": "#9A4B42",
  "info": "#3D6F86",
  "info_tint": "#EDF4F6",
  "muted": "#6F6961",
  "primary": "#243A73",
  "selected_tint": "#EEF1F8",
  "subtle": "#9A9389",
  "success": "#5F7F63",
  "success_tint": "#EFF5ED",
  "surface": "#FFFCF6",
  "surface_alt": "#F1EEE7",
  "surface_inset": "#ECE7DE",
  "text": "#1E1B18",
  "warning": "#B56A3A",
  "warning_tint": "#FAF0E6"
}

Typography:

{
  "base_size": "16px",
  "body_font": "Inter",
  "google_fonts_url": "https://fonts.googleapis.com/css2?family=Inter:wght@400;450;500;600;700&family=IBM+Plex+Mono:wght@400;500;600&display=swap",
  "heading_font": "Inter",
  "letter_spacing": "-0.012em",
  "line_height": 1.58,
  "metric_features": "tabular-nums, slashed-zero for inline values and deltas",
  "mono_font": "IBM Plex Mono"
}

## Visual character to preserve

- Warm white and washi surfaces sit on pale ash gutters with 1px cool-warm borders and no decorative texture.
- Inline metrics use tabular numerals, muted labels, and a small semantic rail, underline, or delta mark rather than a filled badge.
- Marginal analytics occupy narrow right-side or inline note zones, aligned to paragraphs, evidence groups, or recent-change anchors.
- Hover and pressed states change border tone, underline strength, and surface tint by one step, never by dramatic elevation.
- Selection and focus use a deep indigo ring or left hairline that remains visible in dense layouts and high-contrast review.

## ShadSync visual profile

{
  "family": "paper-collage",
  "material": "paper",
  "contour": "pebble",
  "border": "solid",
  "underlay": false,
  "grain": true,
  "stickerBadges": true,
  "motion": "still",
  "density": "dense",
  "accents": [
    "primary",
    "accent",
    "secondary",
    "muted"
  ]
}

## Signature component recipes

### Button
Use `Button` for primary, secondary, outline, and ghost actions. Primary actions must expose the language's strongest contrast pair, while secondary and ghost actions should preserve the surface treatment instead of falling back to default neutral SaaS styling.

### Card
Use `Card`, `CardHeader`, `CardContent`, `CardFooter`, and `CardAction` as the main composition frame. Cards should demonstrate the language's surface, border, hierarchy, and density rules rather than appearing as generic rounded rectangles.

### Input and Textarea
Use `Input` and `Textarea` with visible focus rings, field labels, validation states, and the language's rhythm. Forms should show real product content, not placeholder-only controls.

### Select, Tabs, and Table
Use `Select`, `Tabs`, and `Table` to prove navigation, filtering, and dense data states. The table should show row rhythm, separators, hover/focus states, and an empty or status state when the language calls for it.

### Dialog and Sheet
Use `Dialog` for centered decisions and `Sheet` for contextual editing. Both should inherit the language's spacing, border, overlay, and motion rules.

## Preview shots

- `application-shell`: dashboard or workspace shell with navigation, cards, forms, and state badges.
- `detail-editor`: focused editing flow using input, textarea, select, switch/checkbox, dialog or sheet, and action buttons.
- `data-operations`: table-heavy operational view with tabs, dropdown menu affordances, badges, and destructive/empty states.
- Each preview shot must include a renderable `scene` payload with concrete headline, description, actions, and rows/fields/stats for the UI preview.

## Implementation contract

- Start from local `ui/src/components/ui` shadcn-style primitives; do not create a second component system.
- Apply `/katagami/shadcn/aya-quiet-metrics-interaction-states/registry-theme.json` variables, then use these recipes for composition and state design.
- Preserve Katagami token names as source metadata; shadcn semantic names are only the export surface.
- Do: Keep the main document or task surface visually dominant; place analytics in margins, inline summaries, or quiet context rows.; Use tabular numerals for percentages, counts, timestamps, confidence, and deltas.; Express hover, selected, pressed, and loading states through border, tint, underline, opacity, and rails.; Name tokens semantically while allowing pigment-inspired aliases such as sumi, washi, ai-indigo, and persimmon.; Use low-chroma blue and green for informative and successful states only where labels clarify meaning.; Provide density controls that preserve reading measure and keyboard focus visibility.; Test warning and delta uses of persimmon against warm surfaces for contrast and color-blind ambiguity.
- Do not: Do not turn marginal analytics into KPI cards with large colored backgrounds.; Do not use literal paper fibers, ornamental Japanese motifs, or decorative texture.; Do not rely on dots alone for status; pair with text, notch, underline, or border.; Do not use saturated indigo fills for selection except for the rare primary button.; Do not animate metrics continuously or make loading states pulse aggressively.; Do not let compact density collapse line-height below comfortable reading standards.; Do not assign arbitrary colors to categories when neutral labels and grouping can do the job.

## Copy-paste component example

This generated starter proves the import shape. Production Katagami agents should replace it with a language-specific product composition.

```tsx
import { Badge } from "@/components/ui/badge";
import { Button } from "@/components/ui/button";
import {
  Card,
  CardContent,
  CardDescription,
  CardFooter,
  CardHeader,
  CardTitle,
} from "@/components/ui/card";
import { Input } from "@/components/ui/input";
import { Tabs, TabsList, TabsTrigger } from "@/components/ui/tabs";

export function AyaQuietMetricsAndInteractionStatesShadcnKit() {
  return (
    <section className="grid gap-4 rounded-[var(--radius)] border bg-background p-4 text-foreground">
      <div className="flex items-start justify-between gap-4">
        <div>
          <Badge variant="outline">shadcn/ui</Badge>
          <h2 className="mt-3 text-2xl font-semibold tracking-tight">AYA Quiet Metrics and Interaction States</h2>
          <p className="mt-1 max-w-xl text-sm text-muted-foreground">
            Use the Katagami registry theme, then compose these shadcn primitives
            with the language-specific component recipes.
          </p>
        </div>
        <Button>Apply theme</Button>
      </div>

      <Tabs defaultValue="components">
        <TabsList>
          <TabsTrigger value="components">Components</TabsTrigger>
          <TabsTrigger value="states">States</TabsTrigger>
          <TabsTrigger value="export">Export</TabsTrigger>
        </TabsList>
      </Tabs>

      <Card>
        <CardHeader>
          <CardTitle>Component recipe</CardTitle>
          <CardDescription>
            Replace this starter content with the agent-authored product scene
            from components.md and preview-shots.json.
          </CardDescription>
        </CardHeader>
        <CardContent className="grid gap-3 sm:grid-cols-[1fr_auto]">
          <Input defaultValue="Tokenized shadcn surface" aria-label="Recipe name" />
          <Button variant="secondary">Preview state</Button>
        </CardContent>
        <CardFooter className="justify-between">
          <Badge>Ready</Badge>
          <Button variant="outline">Copy recipe</Button>
        </CardFooter>
      </Card>
    </section>
  );
}
```

## Layout notes

{
  "breakpoints": "Mobile <= 640px stacks marginal analytics below each content anchor; tablet 641-1024px uses a primary column with collapsible insight drawer; desktop >= 1025px supports persistent document spine and marginal rail.",
  "density": "Three density modes: comfortable for long reading, balanced for default analytical work, compact for operations. Density changes vertical padding and label verbosity, not token colors or focus behavior.",
  "grid": "Reading-first 12-column desktop grid: 2-3 columns for project/document context, 6-7 columns for primary reading/workspace, 2-3 columns for marginal analytics. Gutters follow an 8px rhythm with 24px default page padding.",
  "responsive": "Chips wrap in reading order, metric groups collapse to label/value rows, and focus order follows document context before analytics so keyboard users do not get trapped in summary regions.",
  "whitespace": "Use whitespace as hierarchy: 16-24px between content groups, 8-12px inside metric clusters, and fine dividers for transitions between evidence, comments, and status."
}
preview shotscompatibility fallback
{
  "artifact": "katagami:shadcn-preview-shots",
  "version": "preview-shots-v1",
  "generator": "katagami-ui-compatibility-projection",
  "generatedBy": "katagami-ui-projection",
  "requiresVisualProfile": true,
  "schema": "katagami:shadcn-preview-shots/renderable-v1",
  "renderable": true,
  "language": {
    "id": "aya-quiet-metrics-interaction-states",
    "name": "AYA Quiet Metrics and Interaction States",
    "slug": "aya-quiet-metrics-interaction-states"
  },
  "installCommand": "npx shadcn@latest add button card input textarea select dialog sheet tabs badge separator checkbox switch slider tooltip dropdown-menu table",
  "primitives": [
    "button",
    "card",
    "input",
    "textarea",
    "select",
    "dialog",
    "sheet",
    "tabs",
    "badge",
    "separator",
    "checkbox",
    "switch",
    "slider",
    "tooltip",
    "dropdown-menu",
    "table"
  ],
  "identityNotes": [
    "Warm white and washi surfaces sit on pale ash gutters with 1px cool-warm borders and no decorative texture.",
    "Inline metrics use tabular numerals, muted labels, and a small semantic rail, underline, or delta mark rather than a filled badge.",
    "Marginal analytics occupy narrow right-side or inline note zones, aligned to paragraphs, evidence groups, or recent-change anchors.",
    "Hover and pressed states change border tone, underline strength, and surface tint by one step, never by dramatic elevation.",
    "Selection and focus use a deep indigo ring or left hairline that remains visible in dense layouts and high-contrast review."
  ],
  "visualProfile": {
    "family": "paper-collage",
    "material": "paper",
    "contour": "pebble",
    "border": "solid",
    "underlay": false,
    "grain": true,
    "stickerBadges": true,
    "motion": "still",
    "density": "dense",
    "accents": [
      "primary",
      "accent",
      "secondary",
      "muted"
    ]
  },
  "shots": [
    {
      "id": "application-shell",
      "title": "Application shell",
      "viewport": "desktop",
      "primitives": [
        "button",
        "card",
        "input",
        "select",
        "tabs",
        "badge",
        "separator",
        "table"
      ],
      "composition": "A real product workspace with navigation, summary cards, filtering controls, and one dense content region.",
      "mustShow": [
        "primary and secondary actions",
        "card hierarchy",
        "filterable state",
        "table or list density"
      ],
      "avoid": [
        "component inventory walls",
        "placeholder-only content",
        "generic rounded SaaS chrome"
      ],
      "scene": {
        "eyebrow": "workspace spread",
        "headline": "AYA Quiet Metrics and Interaction States launch room",
        "description": "A product team workspace where navigation, filters, metrics, and dense rows carry the language's visible structure.",
        "primaryAction": "Apply theme",
        "secondaryAction": "Review states",
        "stats": [
          {
            "label": "components",
            "value": "16",
            "tone": "accent"
          },
          {
            "label": "states",
            "value": "ready"
          },
          {
            "label": "density",
            "value": "balanced",
            "tone": "warning"
          }
        ],
        "rows": [
          {
            "label": "Primary flow",
            "value": "mapped",
            "status": "active"
          },
          {
            "label": "Token coverage",
            "value": "semantic",
            "status": "synced"
          },
          {
            "label": "Responsive proof",
            "value": "queued",
            "status": "review"
          }
        ],
        "statuses": [
          "Active",
          "Synced",
          "Draft"
        ]
      }
    },
    {
      "id": "detail-editor",
      "title": "Detail editor",
      "viewport": "tablet",
      "primitives": [
        "button",
        "card",
        "input",
        "textarea",
        "select",
        "checkbox",
        "switch",
        "slider",
        "dialog",
        "sheet"
      ],
      "composition": "A focused editing flow with form fields, validation, confirmation, and a contextual side panel.",
      "mustShow": [
        "focus ring",
        "error or destructive state",
        "dialog or sheet treatment",
        "written guidance content"
      ],
      "avoid": [
        "unstyled browser controls",
        "floating cards inside cards",
        "missing labels"
      ],
      "scene": {
        "eyebrow": "editing flow",
        "headline": "Language recipe editor",
        "description": "A focused form proving labels, validation, toggles, panel rhythm, and action hierarchy.",
        "primaryAction": "Save recipe",
        "secondaryAction": "Open sheet",
        "fields": [
          {
            "label": "Component family",
            "value": "Narrative cards"
          },
          {
            "label": "State treatment",
            "value": "Visible focus + validation"
          },
          {
            "label": "Motion",
            "value": "Small lift, no opacity-only fade"
          }
        ],
        "statuses": [
          "Focus",
          "Invalid",
          "Confirmed"
        ]
      }
    },
    {
      "id": "data-operations",
      "title": "Data operations",
      "viewport": "mobile",
      "primitives": [
        "button",
        "tabs",
        "badge",
        "dropdown-menu",
        "table",
        "tooltip",
        "separator"
      ],
      "composition": "A compact operational view proving row rhythm, stacked actions, menu states, badges, and empty/destructive states.",
      "mustShow": [
        "responsive reflow",
        "dense row styling",
        "menu affordance",
        "status badge system"
      ],
      "avoid": [
        "desktop-only tables",
        "text overflow",
        "default shadcn spacing without Katagami character"
      ],
      "scene": {
        "eyebrow": "operations",
        "headline": "Compact review queue",
        "description": "A narrow viewport scene with rows, menus, tooltips, badges, and destructive affordances.",
        "primaryAction": "Resolve",
        "secondaryAction": "Filter",
        "rows": [
          {
            "label": "Button hierarchy",
            "value": "approved",
            "status": "ok"
          },
          {
            "label": "Table rhythm",
            "value": "needs pass",
            "status": "watch"
          },
          {
            "label": "Empty state",
            "value": "designed",
            "status": "done"
          }
        ],
        "statuses": [
          "Queued",
          "Blocked",
          "Done"
        ]
      }
    }
  ],
  "componentRecipes": [
    {
      "primitive": "button",
      "intent": "Prove action hierarchy, focus, disabled, and destructive states."
    },
    {
      "primitive": "card",
      "intent": "Carry the language surface, border, elevation, and density rules."
    },
    {
      "primitive": "input",
      "intent": "Show labels, focus rings, validation, and spacing rhythm."
    },
    {
      "primitive": "textarea",
      "intent": "Show longer guidance, validation copy, and writing density."
    },
    {
      "primitive": "select",
      "intent": "Show filtering, selection contrast, and menu trigger styling."
    },
    {
      "primitive": "dialog",
      "intent": "Show centered decision states and overlay treatment."
    },
    {
      "primitive": "sheet",
      "intent": "Show contextual side panels and responsive editing."
    },
    {
      "primitive": "tabs",
      "intent": "Show navigational structure and active/inactive contrast."
    },
    {
      "primitive": "badge",
      "intent": "Show compact status vocabulary and semantic colors."
    },
    {
      "primitive": "separator",
      "intent": "Show section rhythm without generic gray dividers."
    },
    {
      "primitive": "checkbox",
      "intent": "Show binary selection with visible focus and checked states."
    },
    {
      "primitive": "switch",
      "intent": "Show settings toggles and on/off contrast."
    },
    {
      "primitive": "slider",
      "intent": "Show numeric adjustment with track/thumb styling."
    },
    {
      "primitive": "tooltip",
      "intent": "Show concise explanation styling above compact controls."
    },
    {
      "primitive": "dropdown-menu",
      "intent": "Show action menus, destructive items, and grouped choices."
    },
    {
      "primitive": "table",
      "intent": "Show dense operational data, separators, row states, and responsive behavior."
    }
  ],
  "qualityRules": {
    "do": [
      "Keep the main document or task surface visually dominant; place analytics in margins, inline summaries, or quiet context rows.",
      "Use tabular numerals for percentages, counts, timestamps, confidence, and deltas.",
      "Express hover, selected, pressed, and loading states through border, tint, underline, opacity, and rails.",
      "Name tokens semantically while allowing pigment-inspired aliases such as sumi, washi, ai-indigo, and persimmon.",
      "Use low-chroma blue and green for informative and successful states only where labels clarify meaning.",
      "Provide density controls that preserve reading measure and keyboard focus visibility.",
      "Test warning and delta uses of persimmon against warm surfaces for contrast and color-blind ambiguity."
    ],
    "dont": [
      "Do not turn marginal analytics into KPI cards with large colored backgrounds.",
      "Do not use literal paper fibers, ornamental Japanese motifs, or decorative texture.",
      "Do not rely on dots alone for status; pair with text, notch, underline, or border.",
      "Do not use saturated indigo fills for selection except for the rare primary button.",
      "Do not animate metrics continuously or make loading states pulse aggressively.",
      "Do not let compact density collapse line-height below comfortable reading standards.",
      "Do not assign arbitrary colors to categories when neutral labels and grouping can do the job."
    ]
  }
}