back to gallery
design language·katagami

Katagami

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
Katagami is a restrained cut-paper interface language derived from Japanese stencil craft, where identity comes from subtraction: carved apertures, layered washi, indigo depth, and precise registration marks. It treats screens like assembled sheets rather than floating SaaS cards, balancing cultural craft warmth with editorial utility.
values
precision through subtractionwarm hand-made tactilitylayered depth without visual noiseceremonial calm in interactionlegibility before ornamentmaterial honesty through visible edges
anti-values
×generic flat cards×neon gradients without craft context×unbounded animation×default browser controls×decoration that is not a cut, seam, aperture, or registration mark
tokens
borders5 items
focus
2px solid #B84A39
hairline
1px solid rgba(36,59,83,.72)
heavy cut
3px double #102A43
near invisible
1px solid rgba(16,42,67,.08)
perforated
1px dashed rgba(36,59,83,.72)
colors12 items
accent
#B84A39
accent_foreground
#FFF8EA
background
#F6F0E3
border
#243B53
destructive
#8F2D2D
foreground
#1F2A2E
muted
#EFE2C4
muted_foreground
#5D675F
primary
#102A43
primary_foreground
#F6F0E3
secondary
#C8A45D
secondary_foreground
#1F2A2E
motion5 items
duration base
260ms
duration fast
140ms
duration slow
520ms
easing
cubic-bezier(.2,.7,.2,1)
pattern
small translate lift under 4px, aperture masks slide no more than 6px, opacity fades only for reveals
opacity3 items
disabled
.42
overlay
0.18
wash
0.82
radii6 items
full
999px
lg
14px
md
6px
none
0
sm
2px
xl
24px
shadows4 items
inset paper
inset 0 0 0 1px rgba(16,42,67,.12), inset 0 -18px 45px rgba(200,164,93,.10)
lg
0 28px 70px rgba(16,42,67,.20)
md
0 14px 30px rgba(16,42,67,.14)
sm
0 1px 0 rgba(16,42,67,.20)
spacing10 items
1
4px
2
8px
3
12px
4
16px
5
24px
6
32px
7
48px
8
64px
9
96px
10
128px
surfaces5 items
cut overlay
repeating-linear-gradient(45deg, rgba(16,42,67,.06) 0 1px, transparent 1px 9px)
indigo depth
#102A43
paper
linear-gradient(135deg,#F9F4E8 0%,#EFE2C4 100%)
paper fiber
radial-gradient(circle at 20% 10%, rgba(255,255,255,.45), transparent 28%), linear-gradient(135deg,#F9F4E8,#EFE2C4)
translucent washi
rgba(246,240,227,.82) with backdrop-filter blur(10px)
typography11 items
body font
Inter
body letter spacing
-0.02em
body line height
1.56
display letter spacing
-0.035em
display line height
1.12
google fonts url
https://fonts.googleapis.com/css2?family=IBM+Plex+Mono:wght@400;600&family=Inter:wght@400;500;700&family=Noto+Serif+JP:wght@500;700;900&display=swap
heading font
Noto Serif JP
letter spacing
-0.02em
line height
1.56
mono font
IBM Plex Mono
scale
2xl 2.35rem·3xl 3.4rem·base 1rem·hero 5.4rem·lg 1.22rem·sm 0.9rem·xl 1.58rem·xs 0.78rem
rules
component rules
buttons
rectangular paper or red seal buttons with double borders, clipped corners, and explicit red focus rings
cards
stacked washi sheets with perforated edges, offset pseudo-element shadows, and visible indigo cutouts
forms
custom inputs with paper fill, indigo borders, red focus, and styled checkbox/radio/select controls
navigation
vertical stencil rail or horizontal strip with aperture motifs and registration ticks
composition
Build around one dominant cut-paper sheet and two subordinate utility regions; never use three equal cards in a row.Let indigo negative space appear through apertures at navigation, hero, and data boundaries.Use registration marks to align sections and reveal the grid rather than relying on heavy dividers.Alternate spacious ceremonial moments with compact catalog metadata clusters.Keep accent red to a single primary action or state in each section.Prefer clipped paper silhouettes and punched counters over generic rounded containers.
density
Moderate editorial density: hero and review moments breathe at 96-128px outer spacing, while artifact metadata compresses into 4-12px clusters inside paper panels.
hierarchy
Display headings use Noto Serif JP at tight -0.035em tracking and line-height near 1.12.Body copy uses Inter at 15-16px with -0.02em tracking and 1.56 line-height.Monospaced labels use IBM Plex Mono uppercase with tiny red or gold marks.Indigo wells and aperture reveals carry emphasis before color variation.Primary actions read as red seals while secondary actions remain paper with double indigo borders.
interaction rules
hover lifts are subtle and preserve paper weightfocus states use red outline plus indigo underline or clipped-corner changeloading states reveal a mask pattern instead of spinnersreduced-motion removes sliding apertures and keeps instant state changes
signature patterns
Use layered .washi-panel components with linear-gradient paper texture, clipped polygon corners, 1px indigo hairline borders, and a second offset pseudo-element shadow to show stacked stencil sheets.Create katagami apertures with repeating-radial-gradient or CSS mask-image bands along headers, cards, and navigation rails, always revealing the dark indigo ground through negative space.Pair every primary action with a carved red seal treatment: #B84A39 fill, double indigo outline on hover, and a 4px translate lift using the standard cubic-bezier motion token.Use registration marks and ruled grid lines at section edges; align content to a 12-column editorial grid on desktop and collapse to ceremonial stacked cards on mobile.
layout
breakpoints
desktop
1200px and up
mobile
375px to 767px
tablet
768px to 1199px
density
Moderate; generous 96-128px outer spacing around ceremonial hero and review states, compact 4-12px metadata clusters inside panels, and 24px panel padding distinct from 64px section gaps.
grid

12-column editorial grid, max width 1180px, 24px gutters, with a dominant 7-column washi sheet offset against a 4-column stencil rail or status well.

principles
Use asymmetry like a stencil sheet laid over an indigo backing.Reserve dark indigo for depth wells and high-emphasis panels.Keep margins calm and let border craft carry identity.Create at least one full-bleed or oversized aperture break in every composition.
responsive
Desktop uses asymmetric split composition; tablet collapses to two columns with rail above content at 768px; mobile becomes single-column stacked cards at 560px and preserves aperture borders without horizontal overflow.
whitespace

Whitespace behaves like uncut paper: large quiet margins surround aperture moments, while labels and chips gather tightly near registration marks.

guidance
do
  • Use real paper texture through gradients, pseudo-elements, and subtle noise rather than flat beige fills.
  • Make cutouts, perforations, registration marks, and double borders visible in core navigation and cards.
  • Style every control state, including select, checkbox, radio, focus, disabled, and error states.
  • Maintain WCAG contrast by pairing indigo text with warm paper surfaces and limiting gold to accents.
  • Use one visually dominant panel and let smaller panels support it asymmetrically.
  • Keep red accents scarce so focus and primary actions feel ceremonial.
  • Use 4-12px gaps for related metadata and 96px or more for major section separation.
avoid
  • Do not rely on generic rounded SaaS cards without cut-paper structure.
  • Do not use bright synthetic gradients or glassmorphism unless filtered through washi translucency.
  • Do not animate large panels aggressively; Katagami motion is small, deliberate, and craft-like.
  • Do not place gold text on paper at small sizes because contrast becomes weak.
  • Do not ship default selects, checkboxes, radios, or focus outlines.
  • Do not present the language as a component catalog with sections named Controls, Data, or Feedback.
  • Do not use three equal cards in a row or equal-weight sections.
imagery
hero image direction

overlapping cut-paper sheets revealing indigo apertures and red seal accents

icon style

1.5px indigo line icons with squared terminals and occasional punched-circle counters

illustration style

monochrome indigo stencil silhouettes with uneven washi edges

image gen prompts
Japanese katagami stencil paper layers, indigo dye backing, warm washi texture, editorial UI composition, red seal accent
generative
animation philosophy

slow reveal of cut layers, tiny registration shifts, no looping distraction

shader palette
#F6F0E3#EFE2C4#102A43#B84A39#C8A45D
techniques
CSS gradientsmask-image aperture stripssubtle parallax paper layers
katagami spec
# Katagami

## Philosophy

Katagami is a restrained cut-paper interface language derived from Japanese stencil craft, where identity comes from subtraction: carved apertures, layered washi, indigo depth, and precise registration marks. It treats screens like assembled sheets rather than floating SaaS cards, balancing cultural craft warmth with editorial utility.

### Values

- precision through subtraction
- warm hand-made tactility
- layered depth without visual noise
- ceremonial calm in interaction
- legibility before ornament
- material honesty through visible edges

### Anti-Values

- generic flat cards
- neon gradients without craft context
- unbounded animation
- default browser controls
- decoration that is not a cut, seam, aperture, or registration mark

### Visual Character

- Layered washi panels use #F6F0E3 and #EFE2C4 with subtle paper-fiber gradients, inset shadows, and irregular clipped corners so surfaces feel cut and stacked rather than flat.
- Carved stencil apertures appear as repeating CSS mask patterns, punched border windows, and negative-space motifs that reveal deep indigo #102A43 beneath warm paper layers.
- Hairline registration marks, 1px indigo rules, and dotted perforation borders create craft precision; borders are visible structural elements, not decorative afterthoughts.
- Quiet brush-red accents #B84A39 mark selected states, focus, and primary action sparingly, contrasting with muted sumi text and natural paper neutrals for a disciplined artifact feel.
- Typography pairs a dignified Japanese-influenced serif display voice with a compact modern sans body and monospaced catalog labels to separate ritual headings from functional metadata.

## Tokens

### Borders

- **Focus**: 2px solid #B84A39
- **Hairline**: 1px solid rgba(36,59,83,.72)
- **Heavy Cut**: 3px double #102A43
- **Near Invisible**: 1px solid rgba(16,42,67,.08)
- **Perforated**: 1px dashed rgba(36,59,83,.72)

### Colors

| Name | Value |
|------|-------|
| accent | `#B84A39` |
| accent_foreground | `#FFF8EA` |
| background | `#F6F0E3` |
| border | `#243B53` |
| destructive | `#8F2D2D` |
| foreground | `#1F2A2E` |
| muted | `#EFE2C4` |
| muted_foreground | `#5D675F` |
| primary | `#102A43` |
| primary_foreground | `#F6F0E3` |
| secondary | `#C8A45D` |
| secondary_foreground | `#1F2A2E` |

### Motion

- **Duration Base**: 260ms
- **Duration Fast**: 140ms
- **Duration Slow**: 520ms
- **Easing**: cubic-bezier(.2,.7,.2,1)
- **Pattern**: small translate lift under 4px, aperture masks slide no more than 6px, opacity fades only for reveals

### Opacity

- **Disabled**: .42
- **Overlay**: 0.18
- **Wash**: 0.82

### Radii

- **Full**: 999px
- **Lg**: 14px
- **Md**: 6px
- **None**: 0
- **Sm**: 2px
- **Xl**: 24px

### Shadows

- **Inset Paper**: inset 0 0 0 1px rgba(16,42,67,.12), inset 0 -18px 45px rgba(200,164,93,.10)
- **Lg**: 0 28px 70px rgba(16,42,67,.20)
- **Md**: 0 14px 30px rgba(16,42,67,.14)
- **Sm**: 0 1px 0 rgba(16,42,67,.20)

### Spacing

- **1**: 4px
- **2**: 8px
- **3**: 12px
- **4**: 16px
- **5**: 24px
- **6**: 32px
- **7**: 48px
- **8**: 64px
- **9**: 96px
- **10**: 128px

### Surfaces

- **Cut Overlay**: repeating-linear-gradient(45deg, rgba(16,42,67,.06) 0 1px, transparent 1px 9px)
- **Indigo Depth**: #102A43
- **Paper**: linear-gradient(135deg,#F9F4E8 0%,#EFE2C4 100%)
- **Paper Fiber**: radial-gradient(circle at 20% 10%, rgba(255,255,255,.45), transparent 28%), linear-gradient(135deg,#F9F4E8,#EFE2C4)
- **Translucent Washi**: rgba(246,240,227,.82) with backdrop-filter blur(10px)

### Typography

- **Body Font**: Inter
- **Body Letter Spacing**: -0.02em
- **Body Line Height**: 1.56
- **Display Letter Spacing**: -0.035em
- **Display Line Height**: 1.12
- **Google Fonts Url**: https://fonts.googleapis.com/css2?family=IBM+Plex+Mono:wght@400;600&family=Inter:wght@400;500;700&family=Noto+Serif+JP:wght@500;700;900&display=swap
- **Heading Font**: Noto Serif JP
- **Letter Spacing**: -0.02em
- **Line Height**: 1.56
- **Mono Font**: IBM Plex Mono
- **Scale**: {"2xl":"2.35rem","3xl":"3.4rem","base":"1rem","hero":"5.4rem","lg":"1.22rem","sm":"0.9rem","xl":"1.58rem","xs":"0.78rem"}

## Rules

### Component Rules

- **Buttons**: rectangular paper or red seal buttons with double borders, clipped corners, and explicit red focus rings
- **Cards**: stacked washi sheets with perforated edges, offset pseudo-element shadows, and visible indigo cutouts
- **Forms**: custom inputs with paper fill, indigo borders, red focus, and styled checkbox/radio/select controls
- **Navigation**: vertical stencil rail or horizontal strip with aperture motifs and registration ticks

### Composition

- Build around one dominant cut-paper sheet and two subordinate utility regions; never use three equal cards in a row.
- Let indigo negative space appear through apertures at navigation, hero, and data boundaries.
- Use registration marks to align sections and reveal the grid rather than relying on heavy dividers.
- Alternate spacious ceremonial moments with compact catalog metadata clusters.
- Keep accent red to a single primary action or state in each section.
- Prefer clipped paper silhouettes and punched counters over generic rounded containers.

### Density

Moderate editorial density: hero and review moments breathe at 96-128px outer spacing, while artifact metadata compresses into 4-12px clusters inside paper panels.

### Hierarchy

- Display headings use Noto Serif JP at tight -0.035em tracking and line-height near 1.12.
- Body copy uses Inter at 15-16px with -0.02em tracking and 1.56 line-height.
- Monospaced labels use IBM Plex Mono uppercase with tiny red or gold marks.
- Indigo wells and aperture reveals carry emphasis before color variation.
- Primary actions read as red seals while secondary actions remain paper with double indigo borders.

### Interaction Rules

- hover lifts are subtle and preserve paper weight
- focus states use red outline plus indigo underline or clipped-corner change
- loading states reveal a mask pattern instead of spinners
- reduced-motion removes sliding apertures and keeps instant state changes

### Signature Patterns

- Use layered .washi-panel components with linear-gradient paper texture, clipped polygon corners, 1px indigo hairline borders, and a second offset pseudo-element shadow to show stacked stencil sheets.
- Create katagami apertures with repeating-radial-gradient or CSS mask-image bands along headers, cards, and navigation rails, always revealing the dark indigo ground through negative space.
- Pair every primary action with a carved red seal treatment: #B84A39 fill, double indigo outline on hover, and a 4px translate lift using the standard cubic-bezier motion token.
- Use registration marks and ruled grid lines at section edges; align content to a 12-column editorial grid on desktop and collapse to ceremonial stacked cards on mobile.

## Layout

### Breakpoints

- **Desktop**: 1200px and up
- **Mobile**: 375px to 767px
- **Tablet**: 768px to 1199px

### Density

Moderate; generous 96-128px outer spacing around ceremonial hero and review states, compact 4-12px metadata clusters inside panels, and 24px panel padding distinct from 64px section gaps.

### Grid

12-column editorial grid, max width 1180px, 24px gutters, with a dominant 7-column washi sheet offset against a 4-column stencil rail or status well.

### Principles

- Use asymmetry like a stencil sheet laid over an indigo backing.
- Reserve dark indigo for depth wells and high-emphasis panels.
- Keep margins calm and let border craft carry identity.
- Create at least one full-bleed or oversized aperture break in every composition.

### Responsive

Desktop uses asymmetric split composition; tablet collapses to two columns with rail above content at 768px; mobile becomes single-column stacked cards at 560px and preserves aperture borders without horizontal overflow.

### Whitespace

Whitespace behaves like uncut paper: large quiet margins surround aperture moments, while labels and chips gather tightly near registration marks.

## Guidance

### Do

- Use real paper texture through gradients, pseudo-elements, and subtle noise rather than flat beige fills.
- Make cutouts, perforations, registration marks, and double borders visible in core navigation and cards.
- Style every control state, including select, checkbox, radio, focus, disabled, and error states.
- Maintain WCAG contrast by pairing indigo text with warm paper surfaces and limiting gold to accents.
- Use one visually dominant panel and let smaller panels support it asymmetrically.
- Keep red accents scarce so focus and primary actions feel ceremonial.
- Use 4-12px gaps for related metadata and 96px or more for major section separation.

### Don't

- Do not rely on generic rounded SaaS cards without cut-paper structure.
- Do not use bright synthetic gradients or glassmorphism unless filtered through washi translucency.
- Do not animate large panels aggressively; Katagami motion is small, deliberate, and craft-like.
- Do not place gold text on paper at small sizes because contrast becomes weak.
- Do not ship default selects, checkboxes, radios, or focus outlines.
- Do not present the language as a component catalog with sections named Controls, Data, or Feedback.
- Do not use three equal cards in a row or equal-weight sections.

### Accessibility

- Primary text on paper uses #1F2A2E at contrast above 10:1.
- Interactive focus uses a 2px #B84A39 ring plus shape change for non-color identification.
- Motion is transform-only, below 520ms, and disabled under prefers-reduced-motion.
- Form controls expose visible labels and large touch targets of at least 44px.
- Gold is never used for small body text; it appears as large ornament or paired with indigo.

### Usage Context

- museum collection tools
- editorial publishing dashboards
- artisan marketplace curation
- creative project planning
- cultural archive review workflows

## Imagery Direction

### Hero Image Direction

overlapping cut-paper sheets revealing indigo apertures and red seal accents

### Icon Style

1.5px indigo line icons with squared terminals and occasional punched-circle counters

### Illustration Style

monochrome indigo stencil silhouettes with uneven washi edges

### Image Gen Prompts

- Japanese katagami stencil paper layers, indigo dye backing, warm washi texture, editorial UI composition, red seal accent

## Generative Canvas

### Animation Philosophy

slow reveal of cut layers, tiny registration shifts, no looping distraction

### Shader Palette

- #F6F0E3
- #EFE2C4
- #102A43
- #B84A39
- #C8A45D

### Techniques

- CSS gradients
- mask-image aperture strips
- subtle parallax paper layers
DESIGN.md
---
version: "alpha"
name: "Katagami"
description: "Agent-curated design language exported from Katagami as DESIGN.md."
colors:
  accent: "#B84A39"
  accent_foreground: "#FFF8EA"
  background: "#F6F0E3"
  border: "#243B53"
  destructive: "#8F2D2D"
  foreground: "#1F2A2E"
  muted: "#EFE2C4"
  muted_foreground: "#5D675F"
  primary: "#102A43"
  primary_foreground: "#F6F0E3"
  secondary: "#C8A45D"
  secondary_foreground: "#1F2A2E"
typography:
  headline-lg:
    fontFamily: "Noto Serif JP"
    fontSize: "1.953rem"
    fontWeight: 700
    lineHeight: 1.1
    letterSpacing: "-0.02em"
  headline-md:
    fontFamily: "Noto Serif JP"
    fontSize: "1.563rem"
    fontWeight: 600
    lineHeight: 1.15
    letterSpacing: "-0.02em"
  body-md:
    fontFamily: "Inter"
    fontSize: "16px"
    fontWeight: 400
    lineHeight: 1.5
    letterSpacing: "-0.02em"
  label-md:
    fontFamily: "IBM Plex Mono"
    fontSize: "0.75rem"
    fontWeight: 600
    lineHeight: 1
    letterSpacing: "0.08em"
rounded:
  full: "999px"
  lg: "14px"
  md: "6px"
  none: "0px"
  sm: "2px"
  xl: "24px"
spacing:
  1: "4px"
  2: "8px"
  3: "12px"
  4: "16px"
  5: "24px"
  6: "32px"
  7: "48px"
  8: "64px"
  9: "96px"
  10: "128px"
components:
  color-reference-accent:
    backgroundColor: "{colors.accent}"
  color-reference-accent_foreground:
    backgroundColor: "{colors.accent_foreground}"
  color-reference-background:
    backgroundColor: "{colors.background}"
  color-reference-border:
    backgroundColor: "{colors.border}"
  color-reference-destructive:
    backgroundColor: "{colors.destructive}"
  color-reference-foreground:
    backgroundColor: "{colors.foreground}"
  color-reference-muted:
    backgroundColor: "{colors.muted}"
  color-reference-muted_foreground:
    backgroundColor: "{colors.muted_foreground}"
  color-reference-primary:
    backgroundColor: "{colors.primary}"
  color-reference-primary_foreground:
    backgroundColor: "{colors.primary_foreground}"
  color-reference-secondary:
    backgroundColor: "{colors.secondary}"
  color-reference-secondary_foreground:
    backgroundColor: "{colors.secondary_foreground}"
  button-primary:
    backgroundColor: "{colors.primary}"
    textColor: "#ffffff"
    typography: "{typography.label-md}"
    rounded: "{rounded.md}"
    padding: "12px"
  card-surface:
    backgroundColor: "{colors.background}"
    textColor: "{colors.primary}"
    rounded: "{rounded.md}"
    padding: "16px"
  input-default:
    backgroundColor: "{colors.background}"
    textColor: "{colors.primary}"
    rounded: "{rounded.md}"
    height: "44px"
---

# Katagami

## Overview

Katagami is a restrained cut-paper interface language derived from Japanese stencil craft, where identity comes from subtraction: carved apertures, layered washi, indigo depth, and precise registration marks. It treats screens like assembled sheets rather than floating SaaS cards, balancing cultural craft warmth with editorial utility.

### Values

- precision through subtraction
- warm hand-made tactility
- layered depth without visual noise
- ceremonial calm in interaction
- legibility before ornament
- material honesty through visible edges

### Anti-Values

- generic flat cards
- neon gradients without craft context
- unbounded animation
- default browser controls
- decoration that is not a cut, seam, aperture, or registration mark

### Visual Character

- Layered washi panels use #F6F0E3 and #EFE2C4 with subtle paper-fiber gradients, inset shadows, and irregular clipped corners so surfaces feel cut and stacked rather than flat.
- Carved stencil apertures appear as repeating CSS mask patterns, punched border windows, and negative-space motifs that reveal deep indigo #102A43 beneath warm paper layers.
- Hairline registration marks, 1px indigo rules, and dotted perforation borders create craft precision; borders are visible structural elements, not decorative afterthoughts.
- Quiet brush-red accents #B84A39 mark selected states, focus, and primary action sparingly, contrasting with muted sumi text and natural paper neutrals for a disciplined artifact feel.
- Typography pairs a dignified Japanese-influenced serif display voice with a compact modern sans body and monospaced catalog labels to separate ritual headings from functional metadata.

## 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 | `#B84A39` |
| accent_foreground | `#FFF8EA` |
| background | `#F6F0E3` |
| border | `#243B53` |
| destructive | `#8F2D2D` |
| foreground | `#1F2A2E` |
| muted | `#EFE2C4` |
| muted_foreground | `#5D675F` |
| primary | `#102A43` |
| primary_foreground | `#F6F0E3` |
| secondary | `#C8A45D` |
| secondary_foreground | `#1F2A2E` |

## Typography

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

## Layout

### Spacing Tokens

- **1**: `4px`
- **2**: `8px`
- **3**: `12px`
- **4**: `16px`
- **5**: `24px`
- **6**: `32px`
- **7**: `48px`
- **8**: `64px`
- **9**: `96px`
- **10**: `128px`

### Breakpoints

- **Desktop**: 1200px and up
- **Mobile**: 375px to 767px
- **Tablet**: 768px to 1199px

### Density

Moderate; generous 96-128px outer spacing around ceremonial hero and review states, compact 4-12px metadata clusters inside panels, and 24px panel padding distinct from 64px section gaps.

### Grid

12-column editorial grid, max width 1180px, 24px gutters, with a dominant 7-column washi sheet offset against a 4-column stencil rail or status well.

### Principles

- Use asymmetry like a stencil sheet laid over an indigo backing.
- Reserve dark indigo for depth wells and high-emphasis panels.
- Keep margins calm and let border craft carry identity.
- Create at least one full-bleed or oversized aperture break in every composition.

### Responsive

Desktop uses asymmetric split composition; tablet collapses to two columns with rail above content at 768px; mobile becomes single-column stacked cards at 560px and preserves aperture borders without horizontal overflow.

### Whitespace

Whitespace behaves like uncut paper: large quiet margins surround aperture moments, while labels and chips gather tightly near registration marks.

## Elevation & Depth

### Shadows

- **Inset Paper**: inset 0 0 0 1px rgba(16,42,67,.12), inset 0 -18px 45px rgba(200,164,93,.10)
- **Lg**: 0 28px 70px rgba(16,42,67,.20)
- **Md**: 0 14px 30px rgba(16,42,67,.14)
- **Sm**: 0 1px 0 rgba(16,42,67,.20)

## Shapes

### Rounded

- **Full**: `999px`
- **Lg**: `14px`
- **Md**: `6px`
- **None**: `0px`
- **Sm**: `2px`
- **Xl**: `24px`

### Surfaces

- **Cut Overlay**: repeating-linear-gradient(45deg, rgba(16,42,67,.06) 0 1px, transparent 1px 9px)
- **Indigo Depth**: #102A43
- **Paper**: linear-gradient(135deg,#F9F4E8 0%,#EFE2C4 100%)
- **Paper Fiber**: radial-gradient(circle at 20% 10%, rgba(255,255,255,.45), transparent 28%), linear-gradient(135deg,#F9F4E8,#EFE2C4)
- **Translucent Washi**: rgba(246,240,227,.82) with backdrop-filter blur(10px)

### Borders

- **Focus**: 2px solid #B84A39
- **Hairline**: 1px solid rgba(36,59,83,.72)
- **Heavy Cut**: 3px double #102A43
- **Near Invisible**: 1px solid rgba(16,42,67,.08)
- **Perforated**: 1px dashed rgba(36,59,83,.72)

## Components

### Component Rules

- **Buttons**: rectangular paper or red seal buttons with double borders, clipped corners, and explicit red focus rings
- **Cards**: stacked washi sheets with perforated edges, offset pseudo-element shadows, and visible indigo cutouts
- **Forms**: custom inputs with paper fill, indigo borders, red focus, and styled checkbox/radio/select controls
- **Navigation**: vertical stencil rail or horizontal strip with aperture motifs and registration ticks

### Composition

- Build around one dominant cut-paper sheet and two subordinate utility regions; never use three equal cards in a row.
- Let indigo negative space appear through apertures at navigation, hero, and data boundaries.
- Use registration marks to align sections and reveal the grid rather than relying on heavy dividers.
- Alternate spacious ceremonial moments with compact catalog metadata clusters.
- Keep accent red to a single primary action or state in each section.
- Prefer clipped paper silhouettes and punched counters over generic rounded containers.

### Density

Moderate editorial density: hero and review moments breathe at 96-128px outer spacing, while artifact metadata compresses into 4-12px clusters inside paper panels.

### Hierarchy

- Display headings use Noto Serif JP at tight -0.035em tracking and line-height near 1.12.
- Body copy uses Inter at 15-16px with -0.02em tracking and 1.56 line-height.
- Monospaced labels use IBM Plex Mono uppercase with tiny red or gold marks.
- Indigo wells and aperture reveals carry emphasis before color variation.
- Primary actions read as red seals while secondary actions remain paper with double indigo borders.

### Interaction Rules

- hover lifts are subtle and preserve paper weight
- focus states use red outline plus indigo underline or clipped-corner change
- loading states reveal a mask pattern instead of spinners
- reduced-motion removes sliding apertures and keeps instant state changes

### Signature Patterns

- Use layered .washi-panel components with linear-gradient paper texture, clipped polygon corners, 1px indigo hairline borders, and a second offset pseudo-element shadow to show stacked stencil sheets.
- Create katagami apertures with repeating-radial-gradient or CSS mask-image bands along headers, cards, and navigation rails, always revealing the dark indigo ground through negative space.
- Pair every primary action with a carved red seal treatment: #B84A39 fill, double indigo outline on hover, and a 4px translate lift using the standard cubic-bezier motion token.
- Use registration marks and ruled grid lines at section edges; align content to a 12-column editorial grid on desktop and collapse to ceremonial stacked cards on mobile.

## 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/en-019e04f7-e3ff-7d30-84d1-d688729f9be5/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 Use real paper texture through gradients, pseudo-elements, and subtle noise rather than flat beige fills.
- Do Make cutouts, perforations, registration marks, and double borders visible in core navigation and cards.
- Do Style every control state, including select, checkbox, radio, focus, disabled, and error states.
- Do Maintain WCAG contrast by pairing indigo text with warm paper surfaces and limiting gold to accents.
- Do Use one visually dominant panel and let smaller panels support it asymmetrically.
- Do Keep red accents scarce so focus and primary actions feel ceremonial.
- Do Use 4-12px gaps for related metadata and 96px or more for major section separation.
- Don't Do not rely on generic rounded SaaS cards without cut-paper structure.
- Don't Do not use bright synthetic gradients or glassmorphism unless filtered through washi translucency.
- Don't Do not animate large panels aggressively; Katagami motion is small, deliberate, and craft-like.
- Don't Do not place gold text on paper at small sizes because contrast becomes weak.
- Don't Do not ship default selects, checkboxes, radios, or focus outlines.
- Don't Do not present the language as a component catalog with sections named Controls, Data, or Feedback.
- Don't Do not use three equal cards in a row or equal-weight sections.

### Accessibility

- Primary text on paper uses #1F2A2E at contrast above 10:1.
- Interactive focus uses a 2px #B84A39 ring plus shape change for non-color identification.
- Motion is transform-only, below 520ms, and disabled under prefers-reduced-motion.
- Form controls expose visible labels and large touch targets of at least 44px.
- Gold is never used for small body text; it appears as large ornament or paired with indigo.

### Usage Context

- museum collection tools
- editorial publishing dashboards
- artisan marketplace curation
- creative project planning
- cultural archive review workflows

## Imagery Direction

### Hero Image Direction

overlapping cut-paper sheets revealing indigo apertures and red seal accents

### Icon Style

1.5px indigo line icons with squared terminals and occasional punched-circle counters

### Illustration Style

monochrome indigo stencil silhouettes with uneven washi edges

### Image Gen Prompts

- Japanese katagami stencil paper layers, indigo dye backing, warm washi texture, editorial UI composition, red seal accent

## Generative Canvas

### Animation Philosophy

slow reveal of cut layers, tiny registration shifts, no looping distraction

### Shader Palette

- #F6F0E3
- #EFE2C4
- #102A43
- #B84A39
- #C8A45D

### Techniques

- CSS gradients
- mask-image aperture strips
- subtle parallax paper layers
shadcn/ui theme
```json
{
  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
  "name": "katagami",
  "type": "registry:theme",
  "title": "Katagami shadcn Theme",
  "cssVars": {
    "theme": {},
    "light": {
      "background": "#F6F0E3",
      "foreground": "#1F2A2E",
      "card": "#F6F0E3",
      "card-foreground": "#1F2A2E",
      "popover": "#F6F0E3",
      "popover-foreground": "#1F2A2E",
      "primary": "#102A43",
      "primary-foreground": "#ffffff",
      "secondary": "#C8A45D",
      "secondary-foreground": "#ffffff",
      "muted": "#EFE2C4",
      "muted-foreground": "#5D675F",
      "accent": "#B84A39",
      "accent-foreground": "#ffffff",
      "destructive": "#8F2D2D",
      "border": "#243B53",
      "input": "#243B53",
      "ring": "#B84A39",
      "chart-1": "#102A43",
      "chart-2": "#C8A45D",
      "chart-3": "#B84A39",
      "chart-4": "#16a34a",
      "chart-5": "#d97706",
      "sidebar": "#F6F0E3",
      "sidebar-foreground": "#1F2A2E",
      "sidebar-primary": "#102A43",
      "sidebar-primary-foreground": "#ffffff",
      "sidebar-accent": "#B84A39",
      "sidebar-accent-foreground": "#ffffff",
      "sidebar-border": "#243B53",
      "sidebar-ring": "#B84A39",
      "radius": "6px"
    },
    "dark": {
      "background": "#0f1115",
      "foreground": "#f8fafc",
      "card": "#181b22",
      "card-foreground": "#f8fafc",
      "popover": "#181b22",
      "popover-foreground": "#f8fafc",
      "primary": "#102A43",
      "primary-foreground": "#ffffff",
      "secondary": "#252a33",
      "secondary-foreground": "#f8fafc",
      "muted": "#252a33",
      "muted-foreground": "#a1a1aa",
      "accent": "#B84A39",
      "accent-foreground": "#ffffff",
      "destructive": "#8F2D2D",
      "border": "#303642",
      "input": "#303642",
      "ring": "#B84A39",
      "chart-1": "#102A43",
      "chart-2": "#C8A45D",
      "chart-3": "#B84A39",
      "chart-4": "#16a34a",
      "chart-5": "#d97706",
      "sidebar": "#181b22",
      "sidebar-foreground": "#f8fafc",
      "sidebar-primary": "#102A43",
      "sidebar-primary-foreground": "#ffffff",
      "sidebar-accent": "#B84A39",
      "sidebar-accent-foreground": "#ffffff",
      "sidebar-border": "#303642",
      "sidebar-ring": "#B84A39",
      "radius": "6px"
    }
  },
  "meta": {
    "source": "katagami",
    "languageId": "en-019e04f7-e3ff-7d30-84d1-d688729f9be5",
    "slug": "katagami",
    "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": [
        "focus",
        "hairline",
        "heavy_cut",
        "near_invisible",
        "perforated"
      ],
      "colors": [
        "accent",
        "accent_foreground",
        "background",
        "border",
        "destructive",
        "foreground",
        "muted",
        "muted_foreground",
        "primary",
        "primary_foreground",
        "secondary",
        "secondary_foreground"
      ],
      "motion": [
        "duration_base",
        "duration_fast",
        "duration_slow",
        "easing",
        "pattern"
      ],
      "opacity": [
        "disabled",
        "overlay",
        "wash"
      ],
      "radii": [
        "full",
        "lg",
        "md",
        "none",
        "sm",
        "xl"
      ],
      "shadows": [
        "inset_paper",
        "lg",
        "md",
        "sm"
      ],
      "spacing": [
        "1",
        "10",
        "2",
        "3",
        "4",
        "5",
        "6",
        "7",
        "8",
        "9"
      ],
      "surfaces": [
        "cut_overlay",
        "indigo_depth",
        "paper",
        "paper_fiber",
        "translucent_washi"
      ],
      "typography": [
        "body_font",
        "body_letter_spacing",
        "body_line_height",
        "display_letter_spacing",
        "display_line_height",
        "google_fonts_url",
        "heading_font",
        "letter_spacing",
        "line_height",
        "mono_font",
        "scale"
      ]
    }
  }
}
```
in the wild

embodiments

the full element showcase
embodiment · katagami
DESIGN.md

at a glance

Palette

Typography

headline-lgNoto Serif JP · 31px · 700

The quick brown fox jumps

headline-mdNoto Serif JP · 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

  • 14px
  • 28px
  • 312px
  • 416px
  • 524px
  • 632px
  • 748px
  • 864px
  • 996px
  • 10128px

Shape

full999px
lg14px
md6px
none0px
sm2px
xl24px
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.
primaryaccentsurfacemutedwarningerror
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: #F6F0E3;
  --foreground: #1F2A2E;
  --card: #F6F0E3;
  --card-foreground: #1F2A2E;
  --popover: #F6F0E3;
  --popover-foreground: #1F2A2E;
  --primary: #102A43;
  --primary-foreground: #ffffff;
  --secondary: #C8A45D;
  --secondary-foreground: #ffffff;
  --muted: #EFE2C4;
  --muted-foreground: #5D675F;
  --accent: #B84A39;
  --accent-foreground: #ffffff;
  --destructive: #8F2D2D;
  --border: #243B53;
  --input: #243B53;
  --ring: #B84A39;
  --chart-1: #102A43;
  --chart-2: #C8A45D;
  --chart-3: #B84A39;
  --chart-4: #16a34a;
  --chart-5: #d97706;
  --sidebar: #F6F0E3;
  --sidebar-foreground: #1F2A2E;
  --sidebar-primary: #102A43;
  --sidebar-primary-foreground: #ffffff;
  --sidebar-accent: #B84A39;
  --sidebar-accent-foreground: #ffffff;
  --sidebar-border: #243B53;
  --sidebar-ring: #B84A39;
  --radius: 6px;
}

.dark {
  --background: #0f1115;
  --foreground: #f8fafc;
  --card: #181b22;
  --card-foreground: #f8fafc;
  --popover: #181b22;
  --popover-foreground: #f8fafc;
  --primary: #102A43;
  --primary-foreground: #ffffff;
  --secondary: #252a33;
  --secondary-foreground: #f8fafc;
  --muted: #252a33;
  --muted-foreground: #a1a1aa;
  --accent: #B84A39;
  --accent-foreground: #ffffff;
  --destructive: #8F2D2D;
  --border: #303642;
  --input: #303642;
  --ring: #B84A39;
  --chart-1: #102A43;
  --chart-2: #C8A45D;
  --chart-3: #B84A39;
  --chart-4: #16a34a;
  --chart-5: #d97706;
  --sidebar: #181b22;
  --sidebar-foreground: #f8fafc;
  --sidebar-primary: #102A43;
  --sidebar-primary-foreground: #ffffff;
  --sidebar-accent: #B84A39;
  --sidebar-accent-foreground: #ffffff;
  --sidebar-border: #303642;
  --sidebar-ring: #B84A39;
  --radius: 6px;
}
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 KatagamiShadcnKit() {
  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">Katagami</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 JSONstored + verified
{
  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
  "cssVars": {
    "dark": {
      "accent": "#B84A39",
      "accent-foreground": "#ffffff",
      "background": "#0f1115",
      "border": "#303642",
      "card": "#181b22",
      "card-foreground": "#f8fafc",
      "chart-1": "#102A43",
      "chart-2": "#C8A45D",
      "chart-3": "#B84A39",
      "chart-4": "#16a34a",
      "chart-5": "#d97706",
      "destructive": "#8F2D2D",
      "foreground": "#f8fafc",
      "input": "#303642",
      "muted": "#252a33",
      "muted-foreground": "#a1a1aa",
      "popover": "#181b22",
      "popover-foreground": "#f8fafc",
      "primary": "#102A43",
      "primary-foreground": "#ffffff",
      "radius": "6px",
      "ring": "#B84A39",
      "secondary": "#252a33",
      "secondary-foreground": "#f8fafc",
      "sidebar": "#181b22",
      "sidebar-accent": "#B84A39",
      "sidebar-accent-foreground": "#ffffff",
      "sidebar-border": "#303642",
      "sidebar-foreground": "#f8fafc",
      "sidebar-primary": "#102A43",
      "sidebar-primary-foreground": "#ffffff",
      "sidebar-ring": "#B84A39"
    },
    "light": {
      "accent": "#B84A39",
      "accent-foreground": "#ffffff",
      "background": "#F6F0E3",
      "border": "#243B53",
      "card": "#F6F0E3",
      "card-foreground": "#1F2A2E",
      "chart-1": "#102A43",
      "chart-2": "#C8A45D",
      "chart-3": "#B84A39",
      "chart-4": "#16a34a",
      "chart-5": "#d97706",
      "destructive": "#8F2D2D",
      "foreground": "#1F2A2E",
      "input": "#243B53",
      "muted": "#EFE2C4",
      "muted-foreground": "#5D675F",
      "popover": "#F6F0E3",
      "popover-foreground": "#1F2A2E",
      "primary": "#102A43",
      "primary-foreground": "#ffffff",
      "radius": "6px",
      "ring": "#B84A39",
      "secondary": "#C8A45D",
      "secondary-foreground": "#ffffff",
      "sidebar": "#F6F0E3",
      "sidebar-accent": "#B84A39",
      "sidebar-accent-foreground": "#ffffff",
      "sidebar-border": "#243B53",
      "sidebar-foreground": "#1F2A2E",
      "sidebar-primary": "#102A43",
      "sidebar-primary-foreground": "#ffffff",
      "sidebar-ring": "#B84A39"
    },
    "theme": {}
  },
  "meta": {
    "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",
    "languageId": "en-019e04f7-e3ff-7d30-84d1-d688729f9be5",
    "nativeTokenNames": {
      "borders": [
        "focus",
        "hairline",
        "heavy_cut",
        "near_invisible",
        "perforated"
      ],
      "colors": [
        "accent",
        "accent_foreground",
        "background",
        "border",
        "destructive",
        "foreground",
        "muted",
        "muted_foreground",
        "primary",
        "primary_foreground",
        "secondary",
        "secondary_foreground"
      ],
      "motion": [
        "duration_base",
        "duration_fast",
        "duration_slow",
        "easing",
        "pattern"
      ],
      "opacity": [
        "disabled",
        "overlay",
        "wash"
      ],
      "radii": [
        "full",
        "lg",
        "md",
        "none",
        "sm",
        "xl"
      ],
      "shadows": [
        "inset_paper",
        "lg",
        "md",
        "sm"
      ],
      "spacing": [
        "1",
        "10",
        "2",
        "3",
        "4",
        "5",
        "6",
        "7",
        "8",
        "9"
      ],
      "surfaces": [
        "cut_overlay",
        "indigo_depth",
        "paper",
        "paper_fiber",
        "translucent_washi"
      ],
      "typography": [
        "body_font",
        "body_letter_spacing",
        "body_line_height",
        "display_letter_spacing",
        "display_line_height",
        "google_fonts_url",
        "heading_font",
        "letter_spacing",
        "line_height",
        "mono_font",
        "scale"
      ]
    },
    "slug": "katagami",
    "source": "katagami"
  },
  "name": "katagami",
  "title": "Katagami shadcn Theme",
  "type": "registry:theme"
}
component recipescompatibility fallback
# Katagami shadcn/ui Components

Artifact: `component-recipes-v1`
Author: `katagami-ui-projection`
Language ID: `en-019e04f7-e3ff-7d30-84d1-d688729f9be5`
Slug: `katagami`

## Intent

Katagami is a restrained cut-paper interface language derived from Japanese stencil craft, where identity comes from subtraction: carved apertures, layered washi, indigo depth, and precise registration marks. It treats screens like assembled sheets rather than floating SaaS cards, balancing cultural craft warmth with editorial utility.

## 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": "#B84A39",
  "accent_foreground": "#FFF8EA",
  "background": "#F6F0E3",
  "border": "#243B53",
  "destructive": "#8F2D2D",
  "foreground": "#1F2A2E",
  "muted": "#EFE2C4",
  "muted_foreground": "#5D675F",
  "primary": "#102A43",
  "primary_foreground": "#F6F0E3",
  "secondary": "#C8A45D",
  "secondary_foreground": "#1F2A2E"
}

Typography:

{
  "body_font": "Inter",
  "body_letter_spacing": "-0.02em",
  "body_line_height": "1.56",
  "display_letter_spacing": "-0.035em",
  "display_line_height": "1.12",
  "google_fonts_url": "https://fonts.googleapis.com/css2?family=IBM+Plex+Mono:wght@400;600&family=Inter:wght@400;500;700&family=Noto+Serif+JP:wght@500;700;900&display=swap",
  "heading_font": "Noto Serif JP",
  "letter_spacing": "-0.02em",
  "line_height": "1.56",
  "mono_font": "IBM Plex Mono",
  "scale": {
    "2xl": "2.35rem",
    "3xl": "3.4rem",
    "base": "1rem",
    "hero": "5.4rem",
    "lg": "1.22rem",
    "sm": "0.9rem",
    "xl": "1.58rem",
    "xs": "0.78rem"
  }
}

## Visual character to preserve

- Layered washi panels use #F6F0E3 and #EFE2C4 with subtle paper-fiber gradients, inset shadows, and irregular clipped corners so surfaces feel cut and stacked rather than flat.
- Carved stencil apertures appear as repeating CSS mask patterns, punched border windows, and negative-space motifs that reveal deep indigo #102A43 beneath warm paper layers.
- Hairline registration marks, 1px indigo rules, and dotted perforation borders create craft precision; borders are visible structural elements, not decorative afterthoughts.
- Quiet brush-red accents #B84A39 mark selected states, focus, and primary action sparingly, contrasting with muted sumi text and natural paper neutrals for a disciplined artifact feel.
- Typography pairs a dignified Japanese-influenced serif display voice with a compact modern sans body and monospaced catalog labels to separate ritual headings from functional metadata.

## ShadSync visual profile

{
  "family": "paper-collage",
  "material": "paper",
  "contour": "blob",
  "border": "dashed",
  "underlay": true,
  "grain": true,
  "stickerBadges": false,
  "motion": "lift",
  "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/katagami/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: Use real paper texture through gradients, pseudo-elements, and subtle noise rather than flat beige fills.; Make cutouts, perforations, registration marks, and double borders visible in core navigation and cards.; Style every control state, including select, checkbox, radio, focus, disabled, and error states.; Maintain WCAG contrast by pairing indigo text with warm paper surfaces and limiting gold to accents.; Use one visually dominant panel and let smaller panels support it asymmetrically.; Keep red accents scarce so focus and primary actions feel ceremonial.; Use 4-12px gaps for related metadata and 96px or more for major section separation.
- Do not: Do not rely on generic rounded SaaS cards without cut-paper structure.; Do not use bright synthetic gradients or glassmorphism unless filtered through washi translucency.; Do not animate large panels aggressively; Katagami motion is small, deliberate, and craft-like.; Do not place gold text on paper at small sizes because contrast becomes weak.; Do not ship default selects, checkboxes, radios, or focus outlines.; Do not present the language as a component catalog with sections named Controls, Data, or Feedback.; Do not use three equal cards in a row or equal-weight sections.

## 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 KatagamiShadcnKit() {
  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">Katagami</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": {
    "desktop": "1200px and up",
    "mobile": "375px to 767px",
    "tablet": "768px to 1199px"
  },
  "density": "Moderate; generous 96-128px outer spacing around ceremonial hero and review states, compact 4-12px metadata clusters inside panels, and 24px panel padding distinct from 64px section gaps.",
  "grid": "12-column editorial grid, max width 1180px, 24px gutters, with a dominant 7-column washi sheet offset against a 4-column stencil rail or status well.",
  "principles": [
    "Use asymmetry like a stencil sheet laid over an indigo backing.",
    "Reserve dark indigo for depth wells and high-emphasis panels.",
    "Keep margins calm and let border craft carry identity.",
    "Create at least one full-bleed or oversized aperture break in every composition."
  ],
  "responsive": "Desktop uses asymmetric split composition; tablet collapses to two columns with rail above content at 768px; mobile becomes single-column stacked cards at 560px and preserves aperture borders without horizontal overflow.",
  "whitespace": "Whitespace behaves like uncut paper: large quiet margins surround aperture moments, while labels and chips gather tightly near registration marks."
}
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": "en-019e04f7-e3ff-7d30-84d1-d688729f9be5",
    "name": "Katagami",
    "slug": "katagami"
  },
  "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": [
    "Layered washi panels use #F6F0E3 and #EFE2C4 with subtle paper-fiber gradients, inset shadows, and irregular clipped corners so surfaces feel cut and stacked rather than flat.",
    "Carved stencil apertures appear as repeating CSS mask patterns, punched border windows, and negative-space motifs that reveal deep indigo #102A43 beneath warm paper layers.",
    "Hairline registration marks, 1px indigo rules, and dotted perforation borders create craft precision; borders are visible structural elements, not decorative afterthoughts.",
    "Quiet brush-red accents #B84A39 mark selected states, focus, and primary action sparingly, contrasting with muted sumi text and natural paper neutrals for a disciplined artifact feel.",
    "Typography pairs a dignified Japanese-influenced serif display voice with a compact modern sans body and monospaced catalog labels to separate ritual headings from functional metadata."
  ],
  "visualProfile": {
    "family": "paper-collage",
    "material": "paper",
    "contour": "blob",
    "border": "solid",
    "underlay": true,
    "grain": true,
    "stickerBadges": false,
    "motion": "lift",
    "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": "Katagami 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": [
      "Use real paper texture through gradients, pseudo-elements, and subtle noise rather than flat beige fills.",
      "Make cutouts, perforations, registration marks, and double borders visible in core navigation and cards.",
      "Style every control state, including select, checkbox, radio, focus, disabled, and error states.",
      "Maintain WCAG contrast by pairing indigo text with warm paper surfaces and limiting gold to accents.",
      "Use one visually dominant panel and let smaller panels support it asymmetrically.",
      "Keep red accents scarce so focus and primary actions feel ceremonial.",
      "Use 4-12px gaps for related metadata and 96px or more for major section separation."
    ],
    "dont": [
      "Do not rely on generic rounded SaaS cards without cut-paper structure.",
      "Do not use bright synthetic gradients or glassmorphism unless filtered through washi translucency.",
      "Do not animate large panels aggressively; Katagami motion is small, deliberate, and craft-like.",
      "Do not place gold text on paper at small sizes because contrast becomes weak.",
      "Do not ship default selects, checkboxes, radios, or focus outlines.",
      "Do not present the language as a component catalog with sections named Controls, Data, or Feedback.",
      "Do not use three equal cards in a row or equal-weight sections."
    ]
  }
}
related

More like this