back to gallery
design language·threaded-marginalia-system

Threaded Marginalia System

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
Threaded Marginalia System is a calm, product-grade design language for AYA Katagami: a text-first workspace that gathers many strands of context without making the user leave the document. Its Japanese craft references are translated into interface behavior rather than decoration: katagami precision becomes crisp apertures and cut lines; washi restraint becomes warm ivory surfaces with visible breathing room; weaving becomes a layered information architecture of source threads, margin notes, sidecars, and analytical ticks that sit beside text instead of replacing it. The result is quiet, modern, readable software for synthesis, research, and decision work: primary prose stays central, context is laced into margins, and dashboards become document-adjacent instrumentation rather than a separate spectacle.
values
text remains the primary surface; metrics, status, citations, and model confidence live as adjacent signalsweaving as information architecture: strands of context are traceable, braided, and separable rather than collapsed into one opaque summaryJapanese inspiration through restraint, rhythm, negative space, indigo/sumi/persimmon calibration, and precise cut-paper structure without literal motifslow visual noise for long reading sessions: ivory surfaces, sumi text, pale gray-blue side surfaces, and narrow accents only where they clarify statemarginalia as a first-class interaction layer for comments, provenance, analytics, and side-channel workflow statusdashboard information remains quiet and proximal: inline counters, tiny trend bars, confidence ticks, and compact summaries orbit the documentevery colored mark has a job: focus, link, semantic state, provenance, or warning; never ornament
anti-values
×literal Japanese motifs such as fans, waves, torii gates, sakura, faux brush textures, or tourist-pattern decoration×full-bleed dashboards that replace reading with charts and KPI blocks×dense enterprise chrome, heavy card shadows, low-contrast gray text, or decorative gradients×using indigo, green, or persimmon as large brand fields instead of precise marginal signals×hiding important source relationships behind a single generated summary×making the workspace feel like a mood board rather than a durable productivity tool
tokens
borders4 items
accent width
2px
character
Fine graphite and warm-gray hairlines define paper-like layers; indigo appears as a narrow focus ring, thread rail, or selected-margin rule.
default width
1px
style
solid
colors14 items
accent
#D36C3D
background
#F6F1E8
border
#D8D1C5
error
#B94A3D
info
#244E86
muted
#697178
primary
#244E86
secondary
#6F8794
success
#74897C
surface
#FFFCF5
surface_alt
#F3F6F7
surface_sidecar
#E9F0F3
text
#252525
warning
#D36C3D
motion3 items
duration
140ms
easing
cubic-bezier(0.2, 0, 0, 1)
philosophy
Motion feels like revealing a folded side note: short opacity and 2-4px slide transitions, no bounce, no theatrical paper effects.
radii5 items
full
9999px
lg
18px
md
10px
none
0
sm
6px
shadows3 items
lg
0 18px 48px rgba(37, 37, 37, 0.10)
md
0 8px 24px rgba(37, 37, 37, 0.07)
sm
0 1px 2px rgba(37, 37, 37, 0.04)
spacing2 items
base
8px
scale
4, 8, 12, 16, 24, 32, 40, 48, 64, 80
surfaces3 items
bg pattern
No motif pattern. If texture is needed, use an almost imperceptible warm paper grain or 1px ruled baseline at very low opacity.
card style
Porcelain panel with 18px radius, 1px warm-gray border, no decorative image, and optional 2px indigo or semantic marginal rule clipped inside the left edge.
treatment
Ivory reading plane, porcelain cards, soft gray-blue sidecars, and graphite cut lines. Structure comes from layering, spacing, and margins before fills or shadows.
typography8 items
base size
16px
body font
Inter
google fonts url
https://fonts.googleapis.com/css2?family=IBM+Plex+Sans+JP:wght@400;500;600;700&family=Inter:wght@400;500;600;700&family=IBM+Plex+Mono:wght@400;500;600&display=swap
heading font
IBM Plex Sans JP
letter spacing
-0.01em
line height
1.58
mono font
IBM Plex Mono
scale ratio
1.18
rules
composition
Use a three-layer text workspace: central document/prose column, inner margin for line-linked annotations, and outer sidecar for thread summaries, source bundles, and quiet analytics. On wide screens, keep the reading column dominant and let sidecars behave like marginal instruments. Place context next to the paragraph it qualifies, not in a detached dashboard. Use vertical thread rails, small beads, and short labels to indicate provenance and relationships. Avoid decorative pattern blocks; katagami influence should appear as precise cutouts, alignment apertures, and restrained negative space.
density
Medium-high information density with low visual noise. The document column breathes with 24-32px gutters, while margin and sidecar elements are compact: 12-16px rows, 6-8px gaps, and concise summaries. Collapse long context into threaded bundles that can expand in place. Never let analytics tiles crowd the reading rhythm.
hierarchy
Start hierarchy with typography and placement: sumi headlines, readable graphite body text, muted labels, then indigo only for active links/focus/selected context. Marginal signals should be smaller than the prose they annotate. Use IBM Plex Mono only for IDs, timestamps, source counts, confidence percentages, or tiny analytics labels. Persimmon and green-gray never compete with text; they appear as 2-6px ticks, dots, or slim rules paired with labels.
signature patterns
Thread rail: a 2px indigo vertical line in the margin connecting related notes, sources, and decisions across the document.Marginal tick: 4px by 14px green-gray, persimmon, or indigo mark aligned to a line of text with a short label for status or warning.Context bead stack: tiny bordered circles or squares on the rail representing source types; hover/focus reveals provenance without moving the document.Sidecar digest: soft gray-blue panel containing a three-line summary, source count, confidence sliver, and next action, all subordinate to the document.Cut-line divider: crisp graphite hairline with small stepped offsets to separate folded layers, echoing katagami precision without motif illustration.Inline metric sliver: 40-72px micro-bar or sparkline embedded beside a paragraph label, used for trend or confidence only when it clarifies the text.
layout
breakpoints
Mobile <= 640px stacks document, margin notes, and sidecar digests into collapsible inline blocks; tablet 641-1024px preserves document plus one side rail; desktop >= 1025px shows full threaded marginalia.
density

Text column remains comfortable for sustained reading; margins and sidecars carry compact operational density without overtaking the document.

grid
Desktop uses a 12-column shell with a 680-760px central reading measure, 72-120px inner annotation margin, and 300-360px outer sidecar. Spacing follows an 8px scale with deliberate 24/32px quiet zones around prose.
responsive
On small screens, margin notes become inline disclosure chips anchored after the relevant paragraph. Sidecar analytics move below the active section rather than becoming a separate dashboard page.
whitespace

Whitespace behaves like washi restraint: warm, functional, and rhythmic. Use negative space to separate strands of context before using colored fills.

guidance
do
  • Keep the main document readable before adding context instrumentation.
  • Use margins for provenance, status, annotations, and compact analytics aligned to the relevant text line or paragraph.
  • Treat indigo as the interactive thread color for links, focus, selected notes, and active rails.
  • Use green-gray for calm success/verified states and persimmon for caution or needs-attention states as tiny marks with labels.
  • Create hierarchy through type weight, line length, spacing, and hairline separators before relying on color.
  • Represent weaving through traceable context strands, source bundles, and braided relationships, not literal textile imagery.
  • Style every input, chip, checkbox, and focus state; never leave browser-default controls in an otherwise precise interface.
avoid
  • Do not use sakura, waves, fans, kimono patterns, faux calligraphy, or tourist-Japan iconography.
  • Do not replace the text workspace with large dashboard cards or colorful charts.
  • Do not use indigo, persimmon, or green-gray as broad decorative backgrounds.
  • Do not let source threads become mystery icons without labels or accessible descriptions.
  • Do not hide warnings or model uncertainty behind color alone.
  • Do not over-round the system into generic SaaS softness; keep cut-line precision and quiet geometry.
katagami spec
# Threaded Marginalia System

## Philosophy

Threaded Marginalia System is a calm, product-grade design language for AYA Katagami: a text-first workspace that gathers many strands of context without making the user leave the document. Its Japanese craft references are translated into interface behavior rather than decoration: katagami precision becomes crisp apertures and cut lines; washi restraint becomes warm ivory surfaces with visible breathing room; weaving becomes a layered information architecture of source threads, margin notes, sidecars, and analytical ticks that sit beside text instead of replacing it. The result is quiet, modern, readable software for synthesis, research, and decision work: primary prose stays central, context is laced into margins, and dashboards become document-adjacent instrumentation rather than a separate spectacle.

### Values

- text remains the primary surface; metrics, status, citations, and model confidence live as adjacent signals
- weaving as information architecture: strands of context are traceable, braided, and separable rather than collapsed into one opaque summary
- Japanese inspiration through restraint, rhythm, negative space, indigo/sumi/persimmon calibration, and precise cut-paper structure without literal motifs
- low visual noise for long reading sessions: ivory surfaces, sumi text, pale gray-blue side surfaces, and narrow accents only where they clarify state
- marginalia as a first-class interaction layer for comments, provenance, analytics, and side-channel workflow status
- dashboard information remains quiet and proximal: inline counters, tiny trend bars, confidence ticks, and compact summaries orbit the document
- every colored mark has a job: focus, link, semantic state, provenance, or warning; never ornament

### Anti-Values

- literal Japanese motifs such as fans, waves, torii gates, sakura, faux brush textures, or tourist-pattern decoration
- full-bleed dashboards that replace reading with charts and KPI blocks
- dense enterprise chrome, heavy card shadows, low-contrast gray text, or decorative gradients
- using indigo, green, or persimmon as large brand fields instead of precise marginal signals
- hiding important source relationships behind a single generated summary
- making the workspace feel like a mood board rather than a durable productivity tool

### Visual Character

- A warm ivory document plane sits at the center, flanked by porcelain and soft gray-blue sidecars that feel like quiet folded paper layers.
- Margins carry slim vertical thread rails, source beads, confidence ticks, and short notes aligned to the text line they qualify.
- Indigo marks links, focus, selected threads, and active apertures; subdued green-gray and persimmon appear as tiny semantic ticks or micro-labels only.
- Panels use crisp 1px graphite/sumi borders, very shallow elevation, and carefully cut inner dividers inspired by katagami apertures rather than pattern fills.
- Analytics are compact and document-adjacent: sparkline slivers, inline ratios, small stacked thread counts, and provenance bands, never loud hero charts.

## Tokens

### Borders

- **Accent Width**: 2px
- **Character**: Fine graphite and warm-gray hairlines define paper-like layers; indigo appears as a narrow focus ring, thread rail, or selected-margin rule.
- **Default Width**: 1px
- **Style**: solid

### Colors

| Name | Value |
|------|-------|
| accent | `#D36C3D` |
| background | `#F6F1E8` |
| border | `#D8D1C5` |
| error | `#B94A3D` |
| info | `#244E86` |
| muted | `#697178` |
| primary | `#244E86` |
| secondary | `#6F8794` |
| success | `#74897C` |
| surface | `#FFFCF5` |
| surface_alt | `#F3F6F7` |
| surface_sidecar | `#E9F0F3` |
| text | `#252525` |
| warning | `#D36C3D` |

### Motion

- **Duration**: 140ms
- **Easing**: cubic-bezier(0.2, 0, 0, 1)
- **Philosophy**: Motion feels like revealing a folded side note: short opacity and 2-4px slide transitions, no bounce, no theatrical paper effects.

### Radii

- **Full**: 9999px
- **Lg**: 18px
- **Md**: 10px
- **None**: 0
- **Sm**: 6px

### Shadows

- **Lg**: 0 18px 48px rgba(37, 37, 37, 0.10)
- **Md**: 0 8px 24px rgba(37, 37, 37, 0.07)
- **Sm**: 0 1px 2px rgba(37, 37, 37, 0.04)

### Spacing

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

### Surfaces

- **Bg Pattern**: No motif pattern. If texture is needed, use an almost imperceptible warm paper grain or 1px ruled baseline at very low opacity.
- **Card Style**: Porcelain panel with 18px radius, 1px warm-gray border, no decorative image, and optional 2px indigo or semantic marginal rule clipped inside the left edge.
- **Treatment**: Ivory reading plane, porcelain cards, soft gray-blue sidecars, and graphite cut lines. Structure comes from layering, spacing, and margins before fills or shadows.

### Typography

- **Base Size**: 16px
- **Body Font**: Inter
- **Google Fonts Url**: https://fonts.googleapis.com/css2?family=IBM+Plex+Sans+JP:wght@400;500;600;700&family=Inter:wght@400;500;600;700&family=IBM+Plex+Mono:wght@400;500;600&display=swap
- **Heading Font**: IBM Plex Sans JP
- **Letter Spacing**: -0.01em
- **Line Height**: 1.58
- **Mono Font**: IBM Plex Mono
- **Scale Ratio**: 1.18

## Rules

### Composition

Use a three-layer text workspace: central document/prose column, inner margin for line-linked annotations, and outer sidecar for thread summaries, source bundles, and quiet analytics. On wide screens, keep the reading column dominant and let sidecars behave like marginal instruments. Place context next to the paragraph it qualifies, not in a detached dashboard. Use vertical thread rails, small beads, and short labels to indicate provenance and relationships. Avoid decorative pattern blocks; katagami influence should appear as precise cutouts, alignment apertures, and restrained negative space.

### Density

Medium-high information density with low visual noise. The document column breathes with 24-32px gutters, while margin and sidecar elements are compact: 12-16px rows, 6-8px gaps, and concise summaries. Collapse long context into threaded bundles that can expand in place. Never let analytics tiles crowd the reading rhythm.

### Hierarchy

Start hierarchy with typography and placement: sumi headlines, readable graphite body text, muted labels, then indigo only for active links/focus/selected context. Marginal signals should be smaller than the prose they annotate. Use IBM Plex Mono only for IDs, timestamps, source counts, confidence percentages, or tiny analytics labels. Persimmon and green-gray never compete with text; they appear as 2-6px ticks, dots, or slim rules paired with labels.

### Signature Patterns

- Thread rail: a 2px indigo vertical line in the margin connecting related notes, sources, and decisions across the document.
- Marginal tick: 4px by 14px green-gray, persimmon, or indigo mark aligned to a line of text with a short label for status or warning.
- Context bead stack: tiny bordered circles or squares on the rail representing source types; hover/focus reveals provenance without moving the document.
- Sidecar digest: soft gray-blue panel containing a three-line summary, source count, confidence sliver, and next action, all subordinate to the document.
- Cut-line divider: crisp graphite hairline with small stepped offsets to separate folded layers, echoing katagami precision without motif illustration.
- Inline metric sliver: 40-72px micro-bar or sparkline embedded beside a paragraph label, used for trend or confidence only when it clarifies the text.

## Layout

### Breakpoints

Mobile <= 640px stacks document, margin notes, and sidecar digests into collapsible inline blocks; tablet 641-1024px preserves document plus one side rail; desktop >= 1025px shows full threaded marginalia.

### Density

Text column remains comfortable for sustained reading; margins and sidecars carry compact operational density without overtaking the document.

### Grid

Desktop uses a 12-column shell with a 680-760px central reading measure, 72-120px inner annotation margin, and 300-360px outer sidecar. Spacing follows an 8px scale with deliberate 24/32px quiet zones around prose.

### Responsive

On small screens, margin notes become inline disclosure chips anchored after the relevant paragraph. Sidecar analytics move below the active section rather than becoming a separate dashboard page.

### Whitespace

Whitespace behaves like washi restraint: warm, functional, and rhythmic. Use negative space to separate strands of context before using colored fills.

## Guidance

### Do

- Keep the main document readable before adding context instrumentation.
- Use margins for provenance, status, annotations, and compact analytics aligned to the relevant text line or paragraph.
- Treat indigo as the interactive thread color for links, focus, selected notes, and active rails.
- Use green-gray for calm success/verified states and persimmon for caution or needs-attention states as tiny marks with labels.
- Create hierarchy through type weight, line length, spacing, and hairline separators before relying on color.
- Represent weaving through traceable context strands, source bundles, and braided relationships, not literal textile imagery.
- Style every input, chip, checkbox, and focus state; never leave browser-default controls in an otherwise precise interface.

### Don't

- Do not use sakura, waves, fans, kimono patterns, faux calligraphy, or tourist-Japan iconography.
- Do not replace the text workspace with large dashboard cards or colorful charts.
- Do not use indigo, persimmon, or green-gray as broad decorative backgrounds.
- Do not let source threads become mystery icons without labels or accessible descriptions.
- Do not hide warnings or model uncertainty behind color alone.
- Do not over-round the system into generic SaaS softness; keep cut-line precision and quiet geometry.

### Accessibility

Maintain WCAG AA for all prose and controls against ivory and porcelain surfaces. Pair every colored marginal tick with a text label, icon, shape, or position. Indigo focus rings must be visible at 2px with offset on both ivory and gray-blue sidecars. Do not use pale gray body text below contrast requirements.

### Usage Context

Best for AI research workspaces, synthesis tools, legal or policy review, editorial analysis, knowledge management, and any product where users read, compare sources, and need side-channel analytics without losing the thread of prose.
DESIGN.md
---
version: "alpha"
name: "Threaded Marginalia System"
description: "Agent-curated design language exported from Katagami as DESIGN.md."
colors:
  accent: "#D36C3D"
  background: "#F6F1E8"
  border: "#D8D1C5"
  error: "#B94A3D"
  info: "#244E86"
  muted: "#697178"
  primary: "#244E86"
  secondary: "#6F8794"
  success: "#74897C"
  surface: "#FFFCF5"
  surface_alt: "#F3F6F7"
  surface_sidecar: "#E9F0F3"
  text: "#252525"
  warning: "#D36C3D"
typography:
  headline-lg:
    fontFamily: "IBM Plex Sans JP"
    fontSize: "1.643rem"
    fontWeight: 700
    lineHeight: 1.1
    letterSpacing: "-0.01em"
  headline-md:
    fontFamily: "IBM Plex Sans JP"
    fontSize: "1.392rem"
    fontWeight: 600
    lineHeight: 1.15
    letterSpacing: "-0.01em"
  body-md:
    fontFamily: "Inter"
    fontSize: "16px"
    fontWeight: 400
    lineHeight: 1.58
    letterSpacing: "-0.01em"
  label-md:
    fontFamily: "IBM Plex Mono"
    fontSize: "0.75rem"
    fontWeight: 600
    lineHeight: 1
    letterSpacing: "0.08em"
rounded:
  full: "9999px"
  lg: "18px"
  md: "10px"
  none: "0px"
  sm: "6px"
spacing:
  base: "8px"
  xs: "4px"
  sm: "8px"
  md: "12px"
  lg: "16px"
  xl: "24px"
  2xl: "32px"
  3xl: "40px"
  4xl: "48px"
  step-8: "64px"
  step-9: "80px"
components:
  color-reference-accent:
    backgroundColor: "{colors.accent}"
  color-reference-background:
    backgroundColor: "{colors.background}"
  color-reference-border:
    backgroundColor: "{colors.border}"
  color-reference-error:
    backgroundColor: "{colors.error}"
  color-reference-info:
    backgroundColor: "{colors.info}"
  color-reference-muted:
    backgroundColor: "{colors.muted}"
  color-reference-primary:
    backgroundColor: "{colors.primary}"
  color-reference-secondary:
    backgroundColor: "{colors.secondary}"
  color-reference-success:
    backgroundColor: "{colors.success}"
  color-reference-surface:
    backgroundColor: "{colors.surface}"
  color-reference-surface_alt:
    backgroundColor: "{colors.surface_alt}"
  color-reference-surface_sidecar:
    backgroundColor: "{colors.surface_sidecar}"
  color-reference-text:
    backgroundColor: "{colors.text}"
  color-reference-warning:
    backgroundColor: "{colors.warning}"
  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"
---

# Threaded Marginalia System

## Overview

Threaded Marginalia System is a calm, product-grade design language for AYA Katagami: a text-first workspace that gathers many strands of context without making the user leave the document. Its Japanese craft references are translated into interface behavior rather than decoration: katagami precision becomes crisp apertures and cut lines; washi restraint becomes warm ivory surfaces with visible breathing room; weaving becomes a layered information architecture of source threads, margin notes, sidecars, and analytical ticks that sit beside text instead of replacing it. The result is quiet, modern, readable software for synthesis, research, and decision work: primary prose stays central, context is laced into margins, and dashboards become document-adjacent instrumentation rather than a separate spectacle.

### Values

- text remains the primary surface; metrics, status, citations, and model confidence live as adjacent signals
- weaving as information architecture: strands of context are traceable, braided, and separable rather than collapsed into one opaque summary
- Japanese inspiration through restraint, rhythm, negative space, indigo/sumi/persimmon calibration, and precise cut-paper structure without literal motifs
- low visual noise for long reading sessions: ivory surfaces, sumi text, pale gray-blue side surfaces, and narrow accents only where they clarify state
- marginalia as a first-class interaction layer for comments, provenance, analytics, and side-channel workflow status
- dashboard information remains quiet and proximal: inline counters, tiny trend bars, confidence ticks, and compact summaries orbit the document
- every colored mark has a job: focus, link, semantic state, provenance, or warning; never ornament

### Anti-Values

- literal Japanese motifs such as fans, waves, torii gates, sakura, faux brush textures, or tourist-pattern decoration
- full-bleed dashboards that replace reading with charts and KPI blocks
- dense enterprise chrome, heavy card shadows, low-contrast gray text, or decorative gradients
- using indigo, green, or persimmon as large brand fields instead of precise marginal signals
- hiding important source relationships behind a single generated summary
- making the workspace feel like a mood board rather than a durable productivity tool

### Visual Character

- A warm ivory document plane sits at the center, flanked by porcelain and soft gray-blue sidecars that feel like quiet folded paper layers.
- Margins carry slim vertical thread rails, source beads, confidence ticks, and short notes aligned to the text line they qualify.
- Indigo marks links, focus, selected threads, and active apertures; subdued green-gray and persimmon appear as tiny semantic ticks or micro-labels only.
- Panels use crisp 1px graphite/sumi borders, very shallow elevation, and carefully cut inner dividers inspired by katagami apertures rather than pattern fills.
- Analytics are compact and document-adjacent: sparkline slivers, inline ratios, small stacked thread counts, and provenance bands, never loud hero charts.

## 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 | `#D36C3D` |
| background | `#F6F1E8` |
| border | `#D8D1C5` |
| error | `#B94A3D` |
| info | `#244E86` |
| muted | `#697178` |
| primary | `#244E86` |
| secondary | `#6F8794` |
| success | `#74897C` |
| surface | `#FFFCF5` |
| surface_alt | `#F3F6F7` |
| surface_sidecar | `#E9F0F3` |
| text | `#252525` |
| warning | `#D36C3D` |

## Typography

- **Headline-Lg**: IBM Plex Sans JP, 1.643rem, weight 700, line-height 1.1.
- **Headline-Md**: IBM Plex Sans JP, 1.392rem, 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**: `4px`
- **Sm**: `8px`
- **Md**: `12px`
- **Lg**: `16px`
- **Xl**: `24px`
- **2xl**: `32px`
- **3xl**: `40px`
- **4xl**: `48px`
- **Step-8**: `64px`
- **Step-9**: `80px`

### Breakpoints

Mobile <= 640px stacks document, margin notes, and sidecar digests into collapsible inline blocks; tablet 641-1024px preserves document plus one side rail; desktop >= 1025px shows full threaded marginalia.

### Density

Text column remains comfortable for sustained reading; margins and sidecars carry compact operational density without overtaking the document.

### Grid

Desktop uses a 12-column shell with a 680-760px central reading measure, 72-120px inner annotation margin, and 300-360px outer sidecar. Spacing follows an 8px scale with deliberate 24/32px quiet zones around prose.

### Responsive

On small screens, margin notes become inline disclosure chips anchored after the relevant paragraph. Sidecar analytics move below the active section rather than becoming a separate dashboard page.

### Whitespace

Whitespace behaves like washi restraint: warm, functional, and rhythmic. Use negative space to separate strands of context before using colored fills.

## Elevation & Depth

### Shadows

- **Lg**: 0 18px 48px rgba(37, 37, 37, 0.10)
- **Md**: 0 8px 24px rgba(37, 37, 37, 0.07)
- **Sm**: 0 1px 2px rgba(37, 37, 37, 0.04)

## Shapes

### Rounded

- **Full**: `9999px`
- **Lg**: `18px`
- **Md**: `10px`
- **None**: `0px`
- **Sm**: `6px`

### Surfaces

- **Bg Pattern**: No motif pattern. If texture is needed, use an almost imperceptible warm paper grain or 1px ruled baseline at very low opacity.
- **Card Style**: Porcelain panel with 18px radius, 1px warm-gray border, no decorative image, and optional 2px indigo or semantic marginal rule clipped inside the left edge.
- **Treatment**: Ivory reading plane, porcelain cards, soft gray-blue sidecars, and graphite cut lines. Structure comes from layering, spacing, and margins before fills or shadows.

### Borders

- **Accent Width**: 2px
- **Character**: Fine graphite and warm-gray hairlines define paper-like layers; indigo appears as a narrow focus ring, thread rail, or selected-margin rule.
- **Default Width**: 1px
- **Style**: solid

## Components

### Composition

Use a three-layer text workspace: central document/prose column, inner margin for line-linked annotations, and outer sidecar for thread summaries, source bundles, and quiet analytics. On wide screens, keep the reading column dominant and let sidecars behave like marginal instruments. Place context next to the paragraph it qualifies, not in a detached dashboard. Use vertical thread rails, small beads, and short labels to indicate provenance and relationships. Avoid decorative pattern blocks; katagami influence should appear as precise cutouts, alignment apertures, and restrained negative space.

### Density

Medium-high information density with low visual noise. The document column breathes with 24-32px gutters, while margin and sidecar elements are compact: 12-16px rows, 6-8px gaps, and concise summaries. Collapse long context into threaded bundles that can expand in place. Never let analytics tiles crowd the reading rhythm.

### Hierarchy

Start hierarchy with typography and placement: sumi headlines, readable graphite body text, muted labels, then indigo only for active links/focus/selected context. Marginal signals should be smaller than the prose they annotate. Use IBM Plex Mono only for IDs, timestamps, source counts, confidence percentages, or tiny analytics labels. Persimmon and green-gray never compete with text; they appear as 2-6px ticks, dots, or slim rules paired with labels.

### Signature Patterns

- Thread rail: a 2px indigo vertical line in the margin connecting related notes, sources, and decisions across the document.
- Marginal tick: 4px by 14px green-gray, persimmon, or indigo mark aligned to a line of text with a short label for status or warning.
- Context bead stack: tiny bordered circles or squares on the rail representing source types; hover/focus reveals provenance without moving the document.
- Sidecar digest: soft gray-blue panel containing a three-line summary, source count, confidence sliver, and next action, all subordinate to the document.
- Cut-line divider: crisp graphite hairline with small stepped offsets to separate folded layers, echoing katagami precision without motif illustration.
- Inline metric sliver: 40-72px micro-bar or sparkline embedded beside a paragraph label, used for trend or confidence only when it clarifies the text.

## 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/threaded-marginalia-system/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 readable before adding context instrumentation.
- Do Use margins for provenance, status, annotations, and compact analytics aligned to the relevant text line or paragraph.
- Do Treat indigo as the interactive thread color for links, focus, selected notes, and active rails.
- Do Use green-gray for calm success/verified states and persimmon for caution or needs-attention states as tiny marks with labels.
- Do Create hierarchy through type weight, line length, spacing, and hairline separators before relying on color.
- Do Represent weaving through traceable context strands, source bundles, and braided relationships, not literal textile imagery.
- Do Style every input, chip, checkbox, and focus state; never leave browser-default controls in an otherwise precise interface.
- Don't Do not use sakura, waves, fans, kimono patterns, faux calligraphy, or tourist-Japan iconography.
- Don't Do not replace the text workspace with large dashboard cards or colorful charts.
- Don't Do not use indigo, persimmon, or green-gray as broad decorative backgrounds.
- Don't Do not let source threads become mystery icons without labels or accessible descriptions.
- Don't Do not hide warnings or model uncertainty behind color alone.
- Don't Do not over-round the system into generic SaaS softness; keep cut-line precision and quiet geometry.

### Accessibility

Maintain WCAG AA for all prose and controls against ivory and porcelain surfaces. Pair every colored marginal tick with a text label, icon, shape, or position. Indigo focus rings must be visible at 2px with offset on both ivory and gray-blue sidecars. Do not use pale gray body text below contrast requirements.

### Usage Context

Best for AI research workspaces, synthesis tools, legal or policy review, editorial analysis, knowledge management, and any product where users read, compare sources, and need side-channel analytics without losing the thread of prose.
shadcn/ui theme
```json
{
  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
  "name": "threaded-marginalia-system",
  "type": "registry:theme",
  "title": "Threaded Marginalia System shadcn Theme",
  "cssVars": {
    "theme": {},
    "light": {
      "background": "#F6F1E8",
      "foreground": "#252525",
      "card": "#FFFCF5",
      "card-foreground": "#252525",
      "popover": "#FFFCF5",
      "popover-foreground": "#252525",
      "primary": "#244E86",
      "primary-foreground": "#ffffff",
      "secondary": "#6F8794",
      "secondary-foreground": "#ffffff",
      "muted": "#697178",
      "muted-foreground": "#252525",
      "accent": "#D36C3D",
      "accent-foreground": "#ffffff",
      "destructive": "#B94A3D",
      "border": "#D8D1C5",
      "input": "#D8D1C5",
      "ring": "#D36C3D",
      "chart-1": "#244E86",
      "chart-2": "#6F8794",
      "chart-3": "#D36C3D",
      "chart-4": "#74897C",
      "chart-5": "#D36C3D",
      "sidebar": "#FFFCF5",
      "sidebar-foreground": "#252525",
      "sidebar-primary": "#244E86",
      "sidebar-primary-foreground": "#ffffff",
      "sidebar-accent": "#244E86",
      "sidebar-accent-foreground": "#ffffff",
      "sidebar-border": "#D8D1C5",
      "sidebar-ring": "#D36C3D",
      "radius": "10px"
    },
    "dark": {
      "background": "#0f1115",
      "foreground": "#f8fafc",
      "card": "#181b22",
      "card-foreground": "#f8fafc",
      "popover": "#181b22",
      "popover-foreground": "#f8fafc",
      "primary": "#244E86",
      "primary-foreground": "#ffffff",
      "secondary": "#252a33",
      "secondary-foreground": "#f8fafc",
      "muted": "#252a33",
      "muted-foreground": "#a1a1aa",
      "accent": "#D36C3D",
      "accent-foreground": "#ffffff",
      "destructive": "#B94A3D",
      "border": "#303642",
      "input": "#303642",
      "ring": "#D36C3D",
      "chart-1": "#244E86",
      "chart-2": "#6F8794",
      "chart-3": "#D36C3D",
      "chart-4": "#74897C",
      "chart-5": "#D36C3D",
      "sidebar": "#181b22",
      "sidebar-foreground": "#f8fafc",
      "sidebar-primary": "#244E86",
      "sidebar-primary-foreground": "#ffffff",
      "sidebar-accent": "#D36C3D",
      "sidebar-accent-foreground": "#ffffff",
      "sidebar-border": "#303642",
      "sidebar-ring": "#D36C3D",
      "radius": "10px"
    }
  },
  "meta": {
    "source": "katagami",
    "languageId": "threaded-marginalia-system",
    "slug": "threaded-marginalia-system",
    "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",
        "style"
      ],
      "colors": [
        "accent",
        "background",
        "border",
        "error",
        "info",
        "muted",
        "primary",
        "secondary",
        "success",
        "surface",
        "surface_alt",
        "surface_sidecar",
        "text",
        "warning"
      ],
      "motion": [
        "duration",
        "easing",
        "philosophy"
      ],
      "radii": [
        "full",
        "lg",
        "md",
        "none",
        "sm"
      ],
      "shadows": [
        "lg",
        "md",
        "sm"
      ],
      "spacing": [
        "base",
        "scale"
      ],
      "surfaces": [
        "bg_pattern",
        "card_style",
        "treatment"
      ],
      "typography": [
        "base_size",
        "body_font",
        "google_fonts_url",
        "heading_font",
        "letter_spacing",
        "line_height",
        "mono_font",
        "scale_ratio"
      ]
    }
  }
}
```
in the wild

embodiments

Design Language Preview

Threaded Marginalia System

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-lgIBM Plex Sans JP · 26px · 700

The quick brown fox jumps

headline-mdIBM Plex Sans JP · 22px · 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
  • xs4px
  • sm8px
  • md12px
  • lg16px
  • xl24px
  • 2xl32px
  • 3xl40px
  • 4xl48px
  • step-864px
  • step-980px

Shape

full9999px
lg18px
md10px
none0px
sm6px
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: #F6F1E8;
  --foreground: #252525;
  --card: #FFFCF5;
  --card-foreground: #252525;
  --popover: #FFFCF5;
  --popover-foreground: #252525;
  --primary: #244E86;
  --primary-foreground: #ffffff;
  --secondary: #6F8794;
  --secondary-foreground: #ffffff;
  --muted: #697178;
  --muted-foreground: #252525;
  --accent: #D36C3D;
  --accent-foreground: #ffffff;
  --destructive: #B94A3D;
  --border: #D8D1C5;
  --input: #D8D1C5;
  --ring: #D36C3D;
  --chart-1: #244E86;
  --chart-2: #6F8794;
  --chart-3: #D36C3D;
  --chart-4: #74897C;
  --chart-5: #D36C3D;
  --sidebar: #FFFCF5;
  --sidebar-foreground: #252525;
  --sidebar-primary: #244E86;
  --sidebar-primary-foreground: #ffffff;
  --sidebar-accent: #244E86;
  --sidebar-accent-foreground: #ffffff;
  --sidebar-border: #D8D1C5;
  --sidebar-ring: #D36C3D;
  --radius: 10px;
}

.dark {
  --background: #0f1115;
  --foreground: #f8fafc;
  --card: #181b22;
  --card-foreground: #f8fafc;
  --popover: #181b22;
  --popover-foreground: #f8fafc;
  --primary: #244E86;
  --primary-foreground: #ffffff;
  --secondary: #252a33;
  --secondary-foreground: #f8fafc;
  --muted: #252a33;
  --muted-foreground: #a1a1aa;
  --accent: #D36C3D;
  --accent-foreground: #ffffff;
  --destructive: #B94A3D;
  --border: #303642;
  --input: #303642;
  --ring: #D36C3D;
  --chart-1: #244E86;
  --chart-2: #6F8794;
  --chart-3: #D36C3D;
  --chart-4: #74897C;
  --chart-5: #D36C3D;
  --sidebar: #181b22;
  --sidebar-foreground: #f8fafc;
  --sidebar-primary: #244E86;
  --sidebar-primary-foreground: #ffffff;
  --sidebar-accent: #D36C3D;
  --sidebar-accent-foreground: #ffffff;
  --sidebar-border: #303642;
  --sidebar-ring: #D36C3D;
  --radius: 10px;
}
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 ThreadedMarginaliaSystemShadcnKit() {
  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">Threaded Marginalia System</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": "threaded-marginalia-system",
  "type": "registry:theme",
  "title": "Threaded Marginalia System shadcn Theme",
  "cssVars": {
    "theme": {},
    "light": {
      "background": "#F6F1E8",
      "foreground": "#252525",
      "card": "#FFFCF5",
      "card-foreground": "#252525",
      "popover": "#FFFCF5",
      "popover-foreground": "#252525",
      "primary": "#244E86",
      "primary-foreground": "#ffffff",
      "secondary": "#6F8794",
      "secondary-foreground": "#ffffff",
      "muted": "#697178",
      "muted-foreground": "#252525",
      "accent": "#D36C3D",
      "accent-foreground": "#ffffff",
      "destructive": "#B94A3D",
      "border": "#D8D1C5",
      "input": "#D8D1C5",
      "ring": "#D36C3D",
      "chart-1": "#244E86",
      "chart-2": "#6F8794",
      "chart-3": "#D36C3D",
      "chart-4": "#74897C",
      "chart-5": "#D36C3D",
      "sidebar": "#FFFCF5",
      "sidebar-foreground": "#252525",
      "sidebar-primary": "#244E86",
      "sidebar-primary-foreground": "#ffffff",
      "sidebar-accent": "#244E86",
      "sidebar-accent-foreground": "#ffffff",
      "sidebar-border": "#D8D1C5",
      "sidebar-ring": "#D36C3D",
      "radius": "10px"
    },
    "dark": {
      "background": "#0f1115",
      "foreground": "#f8fafc",
      "card": "#181b22",
      "card-foreground": "#f8fafc",
      "popover": "#181b22",
      "popover-foreground": "#f8fafc",
      "primary": "#244E86",
      "primary-foreground": "#ffffff",
      "secondary": "#252a33",
      "secondary-foreground": "#f8fafc",
      "muted": "#252a33",
      "muted-foreground": "#a1a1aa",
      "accent": "#D36C3D",
      "accent-foreground": "#ffffff",
      "destructive": "#B94A3D",
      "border": "#303642",
      "input": "#303642",
      "ring": "#D36C3D",
      "chart-1": "#244E86",
      "chart-2": "#6F8794",
      "chart-3": "#D36C3D",
      "chart-4": "#74897C",
      "chart-5": "#D36C3D",
      "sidebar": "#181b22",
      "sidebar-foreground": "#f8fafc",
      "sidebar-primary": "#244E86",
      "sidebar-primary-foreground": "#ffffff",
      "sidebar-accent": "#D36C3D",
      "sidebar-accent-foreground": "#ffffff",
      "sidebar-border": "#303642",
      "sidebar-ring": "#D36C3D",
      "radius": "10px"
    }
  },
  "meta": {
    "source": "katagami",
    "languageId": "threaded-marginalia-system",
    "slug": "threaded-marginalia-system",
    "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",
        "style"
      ],
      "colors": [
        "accent",
        "background",
        "border",
        "error",
        "info",
        "muted",
        "primary",
        "secondary",
        "success",
        "surface",
        "surface_alt",
        "surface_sidecar",
        "text",
        "warning"
      ],
      "motion": [
        "duration",
        "easing",
        "philosophy"
      ],
      "radii": [
        "full",
        "lg",
        "md",
        "none",
        "sm"
      ],
      "shadows": [
        "lg",
        "md",
        "sm"
      ],
      "spacing": [
        "base",
        "scale"
      ],
      "surfaces": [
        "bg_pattern",
        "card_style",
        "treatment"
      ],
      "typography": [
        "base_size",
        "body_font",
        "google_fonts_url",
        "heading_font",
        "letter_spacing",
        "line_height",
        "mono_font",
        "scale_ratio"
      ]
    }
  }
}
component recipescompatibility fallback
# Threaded Marginalia System shadcn/ui Components

Artifact: `component-recipes-v1`
Author: `katagami-ui-projection`
Language ID: `threaded-marginalia-system`
Slug: `threaded-marginalia-system`

## Intent

Threaded Marginalia System is a calm, product-grade design language for AYA Katagami: a text-first workspace that gathers many strands of context without making the user leave the document. Its Japanese craft references are translated into interface behavior rather than decoration: katagami precision becomes crisp apertures and cut lines; washi restraint becomes warm ivory surfaces with visible breathing room; weaving becomes a layered information architecture of source threads, margin notes, sidecars, and analytical ticks that sit beside text instead of replacing it. The result is quiet, modern, readable software for synthesis, research, and decision work: primary prose stays central, context is laced into margins, and dashboards become document-adjacent instrumentation rather than a separate spectacle.

## 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": "#D36C3D",
  "background": "#F6F1E8",
  "border": "#D8D1C5",
  "error": "#B94A3D",
  "info": "#244E86",
  "muted": "#697178",
  "primary": "#244E86",
  "secondary": "#6F8794",
  "success": "#74897C",
  "surface": "#FFFCF5",
  "surface_alt": "#F3F6F7",
  "surface_sidecar": "#E9F0F3",
  "text": "#252525",
  "warning": "#D36C3D"
}

Typography:

{
  "base_size": "16px",
  "body_font": "Inter",
  "google_fonts_url": "https://fonts.googleapis.com/css2?family=IBM+Plex+Sans+JP:wght@400;500;600;700&family=Inter:wght@400;500;600;700&family=IBM+Plex+Mono:wght@400;500;600&display=swap",
  "heading_font": "IBM Plex Sans JP",
  "letter_spacing": "-0.01em",
  "line_height": 1.58,
  "mono_font": "IBM Plex Mono",
  "scale_ratio": 1.18
}

## Visual character to preserve

- A warm ivory document plane sits at the center, flanked by porcelain and soft gray-blue sidecars that feel like quiet folded paper layers.
- Margins carry slim vertical thread rails, source beads, confidence ticks, and short notes aligned to the text line they qualify.
- Indigo marks links, focus, selected threads, and active apertures; subdued green-gray and persimmon appear as tiny semantic ticks or micro-labels only.
- Panels use crisp 1px graphite/sumi borders, very shallow elevation, and carefully cut inner dividers inspired by katagami apertures rather than pattern fills.
- Analytics are compact and document-adjacent: sparkline slivers, inline ratios, small stacked thread counts, and provenance bands, never loud hero charts.

## ShadSync visual profile

{
  "family": "paper-collage",
  "material": "paper",
  "contour": "default",
  "border": "solid",
  "underlay": true,
  "grain": true,
  "stickerBadges": false,
  "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/threaded-marginalia-system/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 readable before adding context instrumentation.; Use margins for provenance, status, annotations, and compact analytics aligned to the relevant text line or paragraph.; Treat indigo as the interactive thread color for links, focus, selected notes, and active rails.; Use green-gray for calm success/verified states and persimmon for caution or needs-attention states as tiny marks with labels.; Create hierarchy through type weight, line length, spacing, and hairline separators before relying on color.; Represent weaving through traceable context strands, source bundles, and braided relationships, not literal textile imagery.; Style every input, chip, checkbox, and focus state; never leave browser-default controls in an otherwise precise interface.
- Do not: Do not use sakura, waves, fans, kimono patterns, faux calligraphy, or tourist-Japan iconography.; Do not replace the text workspace with large dashboard cards or colorful charts.; Do not use indigo, persimmon, or green-gray as broad decorative backgrounds.; Do not let source threads become mystery icons without labels or accessible descriptions.; Do not hide warnings or model uncertainty behind color alone.; Do not over-round the system into generic SaaS softness; keep cut-line precision and quiet geometry.

## 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 ThreadedMarginaliaSystemShadcnKit() {
  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">Threaded Marginalia System</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 document, margin notes, and sidecar digests into collapsible inline blocks; tablet 641-1024px preserves document plus one side rail; desktop >= 1025px shows full threaded marginalia.",
  "density": "Text column remains comfortable for sustained reading; margins and sidecars carry compact operational density without overtaking the document.",
  "grid": "Desktop uses a 12-column shell with a 680-760px central reading measure, 72-120px inner annotation margin, and 300-360px outer sidecar. Spacing follows an 8px scale with deliberate 24/32px quiet zones around prose.",
  "responsive": "On small screens, margin notes become inline disclosure chips anchored after the relevant paragraph. Sidecar analytics move below the active section rather than becoming a separate dashboard page.",
  "whitespace": "Whitespace behaves like washi restraint: warm, functional, and rhythmic. Use negative space to separate strands of context before using colored fills."
}
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": "threaded-marginalia-system",
    "name": "Threaded Marginalia System",
    "slug": "threaded-marginalia-system"
  },
  "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": [
    "A warm ivory document plane sits at the center, flanked by porcelain and soft gray-blue sidecars that feel like quiet folded paper layers.",
    "Margins carry slim vertical thread rails, source beads, confidence ticks, and short notes aligned to the text line they qualify.",
    "Indigo marks links, focus, selected threads, and active apertures; subdued green-gray and persimmon appear as tiny semantic ticks or micro-labels only.",
    "Panels use crisp 1px graphite/sumi borders, very shallow elevation, and carefully cut inner dividers inspired by katagami apertures rather than pattern fills.",
    "Analytics are compact and document-adjacent: sparkline slivers, inline ratios, small stacked thread counts, and provenance bands, never loud hero charts."
  ],
  "visualProfile": {
    "family": "paper-collage",
    "material": "paper",
    "contour": "default",
    "border": "solid",
    "underlay": true,
    "grain": true,
    "stickerBadges": false,
    "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": "Threaded Marginalia System 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 readable before adding context instrumentation.",
      "Use margins for provenance, status, annotations, and compact analytics aligned to the relevant text line or paragraph.",
      "Treat indigo as the interactive thread color for links, focus, selected notes, and active rails.",
      "Use green-gray for calm success/verified states and persimmon for caution or needs-attention states as tiny marks with labels.",
      "Create hierarchy through type weight, line length, spacing, and hairline separators before relying on color.",
      "Represent weaving through traceable context strands, source bundles, and braided relationships, not literal textile imagery.",
      "Style every input, chip, checkbox, and focus state; never leave browser-default controls in an otherwise precise interface."
    ],
    "dont": [
      "Do not use sakura, waves, fans, kimono patterns, faux calligraphy, or tourist-Japan iconography.",
      "Do not replace the text workspace with large dashboard cards or colorful charts.",
      "Do not use indigo, persimmon, or green-gray as broad decorative backgrounds.",
      "Do not let source threads become mystery icons without labels or accessible descriptions.",
      "Do not hide warnings or model uncertainty behind color alone.",
      "Do not over-round the system into generic SaaS softness; keep cut-line precision and quiet geometry."
    ]
  }
}