Zhuwen

# Zhuwen

## Philosophy

朱文 — the carved-relief seal style, where characters stand in cinnabar against the paper. Zhuwen carries the grammar of zhuan ke (seal carving) into the interface: each control presses into a warm xuan-paper field like a chop meeting cinnabar paste — square, deliberate, irreversible in its clarity. It is the design language for the things a seal proves: catalogues, provenance trails, and authentication desks. The signature mechanic is the decisive press — controls do not float; on activation a stamp drops one pixel and the cinnabar deepens, the way real seal paste meets paper. Carved negative space does as much work as the ink.

### Values

- Carved with intention — purposeful form, no decorative excess
- Red and white in dynamic tension — the yin-yang of carved and uncarved space
- Square geometry honours the seal stone — sharp edges convey authority and permanence
- Hierarchy from weight and position, like characters composed within a seal face
- The press is decisive — interactions resolve with the finality of ink meeting paper

### Anti-Values

- Rounded corners — seals are carved from square stone
- Floating soft drop-shadows that lift elements off the page
- Gradients and photographic backgrounds — the field is ink-on-paper abstraction
- Pills and circular badges — seal forms are square
- Cold white screens — the ground is warm xuan-paper
- Bounce or elastic easing — the press is firm

## Tokens

### Colors

| Name | Value |
|------|-------|
| bg | `#F1E7D2` |
| surface | `#FBF4E3` |
| surface_2 | `#EADFC6` |
| text | `#241C14` |
| muted | `#756A55` |
| border | `#D8CBAE` |
| accent | `#C0271F` |
| accent_deep | `#8F1B16` |
| on_accent | `#FBF4E3` |
| gold | `#9A6A1E` |
| success | `#4F6B34` |
| warning | `#9A6A1E` |
| error | `#A8201A` |
| info | `#355A78` |
| primary | `#C0271F` |
| secondary | `#241C14` |

### Typography

- **Base Size**: 17px
- **Body Font**: Noto Sans SC
- **Heading Font**: Noto Serif SC
- **Mono Font**: Fira Code
- **Heading Weight**: 900
- **Heading Transform**: none
- **Letter Spacing**: -0.02em
- **Line Height**: 1.62
- **Google Fonts Url**: https://fonts.googleapis.com/css2?family=Noto+Serif+SC:wght@500;700;900&family=Noto+Sans+SC:wght@400;500;700&family=Fira+Code:wght@500&display=swap

### Radii

- **None**: 0px
- **Sm**: 0px
- **Md**: 0px
- **Lg**: 0px
- **Full**: 0px

### Shadows

- **Carve Sm**: inset 0 1px 2px rgba(36,28,20,.14)
- **Carve Md**: inset 0 2px 6px rgba(36,28,20,.18), inset 0 0 0 1px rgba(36,28,20,.06)
- **Stamp**: inset 0 2px 0 rgba(143,27,22,.45), inset 0 -2px 0 rgba(0,0,0,.10)
- **Stone**: 6px 6px 0 rgba(36,28,20,.10)

### Spacing

- **Base**: 8px
- **Scale**: ["4px","8px","12px","16px","24px","32px","48px","64px","96px","128px"]

### Surfaces

- **Treatment**: warm xuan-paper field with subtle CSS fiber speckle and flat cinnabar stamp surfaces
- **Card Style**: surface behind a 3px dark inset stroke (square seal-stone frame) with a hard offset stone-shadow; carved, never floating
- **Bg Pattern**: radial paper-fiber speckle dots via CSS gradients only; no photographic imagery

### Borders

- **Default Width**: 3px
- **Accent Width**: 3px
- **Style**: solid as inset stroke
- **Character**: square seal-stone frames realised as inset box-shadow strokes; thick cinnabar top rule on data regions; never rounded, never a single accent edge

### Motion

- **Duration**: 150ms
- **Easing**: cubic-bezier(0.2,0,0.3,1)
- **Philosophy**: firm decisive press: controls translate down one pixel and the cinnabar deepens as if paste meets paper; no bounce or elastic easing; settled state is the no-JS default, motion layered on top

## Rules

### Composition

Build layouts on a square grid module, content capped at 1160-1200px and centred (only the landing hero spans 100vw). Elements align to strong horizontal and vertical axes, like the grid of characters within a seal face. Negative space is active — the uncarved area defines the carved. Group related content behind square dark inset frames that echo a seal stone.

### Hierarchy

Primary emphasis through size and cinnabar red; secondary through serif weight and dark ink; tertiary through muted stone gray. Headings are carved-in: large, dark, Noto Serif SC 900. Body flows like brush annotations. Interactive elements stamp forward like freshly pressed chops.

### Density

Medium-high. Seal compositions pack meaning into square spaces; the UI is structured and information-rich without crowding. Consistent 8px spacing units and inset stone frames separate content zones.

### Signature

The decisive press: every control presses inward via inset/stamp shadows and deepens the cinnabar on activation. Five named patterns — Stamp Button, Seal Badge, Stone Card, Imprint Table, Chop-Mark Divider — each appearing live in the embodiment.

## Layout

### Grid

Square module; CSS grid with minmax(0,1fr) + min-width:0 so children shrink, never overflow; content max-width 1160-1200px centred.

### Whitespace

Generous; section gaps 96px, card padding 32px; always pad above titles.

### Density

medium-high

### Responsive

390px mobile to 2560px+ ultra-wide. Mobile stacks to one column, hides non-essential nav links and secondary table columns, never overflows horizontally. Ultra-wide caps and centres content; only the hero spans 100vw.

### Breakpoints

- **Mobile**: 390px
- **Tablet**: 720px
- **Desktop**: 980px
- **Wide**: 1200px

## Guidance

### Do

- Press cinnabar (#C0271F) onto warm xuan-paper for primary actions and emphasis
- Keep everything square — radius 0; sharp edges convey authority
- Use inset and stamp shadows to carve controls inward, never floating drops
- Compose on a strong grid, aligned like characters in a seal face
- Make one button clearly primary; keep the rest quieter; share one shape and height
- Use seal badges with text or characters, not colour alone, for status
- Use Noto Serif SC 900 for headings to evoke the structured strokes of seal script
- Reserve seal-gold for authentication and certification marks

### Don't

- Never round corners — seals are carved from square stone
- Avoid gradients and photographic backgrounds — the field is ink-on-paper abstraction (the swappable hero image excepted)
- Do not use floating soft drop-shadows; prefer inset/offset shadows that carve
- Never mix more than three accents in one component
- Never use pills or circular badges; never a single accent edge on a card
- No emoji or symbol glyphs in copy, markup, or on buttons
- Do not trap navigation in a floating boxed pill

### Accessibility

WCAG AA contrast: cinnabar on paper ~4.6:1, dark ink on paper ~13:1, paper-white on cinnabar ~4.7:1. Focus states use a 2px cinnabar inset ring. Touch targets meet 44px. Colour is never the sole indicator — seal badges carry text or characters. Semantic heading order preserved. prefers-reduced-motion respected.

## Imagery Direction

### Pairs With

cinnabar

### Summary

Imagery is hand-pressed cinnabar seal impressions: bold flat vermilion-red carved strokes stamped onto warm cream xuan-paper, forms emerging from carved negative space, grainy mottled edges with fiber gaps, flat single-color with no gradients, composed on a strong square axis and filling the frame edge to edge.

### Subjects

- cranes over mountain peaks
- leaping carp
- auspicious clouds
- pine and rock
- scrolls and chops
- heritage motifs

### Usage

One full-bleed cinnabar impression as the landing hero (swapped via --hero-image); compact chops for features and avatars; sparser half-inked impressions for empty states.

---
version: "alpha"
name: "Zhuwen"
description: "Agent-curated design language exported from Katagami as DESIGN.md."
colors:
  bg: "#F1E7D2"
  surface: "#FBF4E3"
  surface_2: "#EADFC6"
  text: "#241C14"
  muted: "#756A55"
  border: "#D8CBAE"
  accent: "#C0271F"
  accent_deep: "#8F1B16"
  on_accent: "#FBF4E3"
  gold: "#9A6A1E"
  success: "#4F6B34"
  warning: "#9A6A1E"
  error: "#A8201A"
  info: "#355A78"
  primary: "#C0271F"
  secondary: "#241C14"
typography:
  headline-lg:
    fontFamily: "Noto Serif SC"
    fontSize: "2.075rem"
    fontWeight: 700
    lineHeight: 1.1
    letterSpacing: "-0.02em"
  headline-md:
    fontFamily: "Noto Serif SC"
    fontSize: "1.66rem"
    fontWeight: 600
    lineHeight: 1.15
    letterSpacing: "-0.02em"
  body-md:
    fontFamily: "Noto Sans SC"
    fontSize: "17px"
    fontWeight: 400
    lineHeight: 1.5
    letterSpacing: "-0.02em"
  label-md:
    fontFamily: "Fira Code"
    fontSize: "0.75rem"
    fontWeight: 600
    lineHeight: 1
    letterSpacing: "0.08em"
rounded:
  none: "0px"
  sm: "0px"
  md: "0px"
  lg: "0px"
  full: "0px"
spacing:
  base: "8px"
  xs: "4px"
  sm: "8px"
  md: "12px"
  lg: "16px"
  xl: "24px"
  2xl: "32px"
  3xl: "48px"
  4xl: "64px"
  step-8: "96px"
  step-9: "128px"
components:
  color-reference-bg:
    backgroundColor: "{colors.bg}"
  color-reference-surface:
    backgroundColor: "{colors.surface}"
  color-reference-surface_2:
    backgroundColor: "{colors.surface_2}"
  color-reference-text:
    backgroundColor: "{colors.text}"
  color-reference-muted:
    backgroundColor: "{colors.muted}"
  color-reference-border:
    backgroundColor: "{colors.border}"
  color-reference-accent:
    backgroundColor: "{colors.accent}"
  color-reference-accent_deep:
    backgroundColor: "{colors.accent_deep}"
  color-reference-on_accent:
    backgroundColor: "{colors.on_accent}"
  color-reference-gold:
    backgroundColor: "{colors.gold}"
  color-reference-success:
    backgroundColor: "{colors.success}"
  color-reference-warning:
    backgroundColor: "{colors.warning}"
  color-reference-error:
    backgroundColor: "{colors.error}"
  color-reference-info:
    backgroundColor: "{colors.info}"
  color-reference-primary:
    backgroundColor: "{colors.primary}"
  color-reference-secondary:
    backgroundColor: "{colors.secondary}"
  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"
---

# Zhuwen

## Overview

朱文 — the carved-relief seal style, where characters stand in cinnabar against the paper. Zhuwen carries the grammar of zhuan ke (seal carving) into the interface: each control presses into a warm xuan-paper field like a chop meeting cinnabar paste — square, deliberate, irreversible in its clarity. It is the design language for the things a seal proves: catalogues, provenance trails, and authentication desks. The signature mechanic is the decisive press — controls do not float; on activation a stamp drops one pixel and the cinnabar deepens, the way real seal paste meets paper. Carved negative space does as much work as the ink.

### Values

- Carved with intention — purposeful form, no decorative excess
- Red and white in dynamic tension — the yin-yang of carved and uncarved space
- Square geometry honours the seal stone — sharp edges convey authority and permanence
- Hierarchy from weight and position, like characters composed within a seal face
- The press is decisive — interactions resolve with the finality of ink meeting paper

### Anti-Values

- Rounded corners — seals are carved from square stone
- Floating soft drop-shadows that lift elements off the page
- Gradients and photographic backgrounds — the field is ink-on-paper abstraction
- Pills and circular badges — seal forms are square
- Cold white screens — the ground is warm xuan-paper
- Bounce or elastic easing — the press is firm

## Colors

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

| Token | Value |
|-------|-------|
| bg | `#F1E7D2` |
| surface | `#FBF4E3` |
| surface_2 | `#EADFC6` |
| text | `#241C14` |
| muted | `#756A55` |
| border | `#D8CBAE` |
| accent | `#C0271F` |
| accent_deep | `#8F1B16` |
| on_accent | `#FBF4E3` |
| gold | `#9A6A1E` |
| success | `#4F6B34` |
| warning | `#9A6A1E` |
| error | `#A8201A` |
| info | `#355A78` |
| primary | `#C0271F` |
| secondary | `#241C14` |

## Typography

- **Headline-Lg**: Noto Serif SC, 2.075rem, weight 700, line-height 1.1.
- **Headline-Md**: Noto Serif SC, 1.66rem, weight 600, line-height 1.15.
- **Body-Md**: Noto Sans SC, 17px, weight 400, line-height 1.5.
- **Label-Md**: Fira Code, 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**: `48px`
- **4xl**: `64px`
- **Step-8**: `96px`
- **Step-9**: `128px`

### Grid

Square module; CSS grid with minmax(0,1fr) + min-width:0 so children shrink, never overflow; content max-width 1160-1200px centred.

### Whitespace

Generous; section gaps 96px, card padding 32px; always pad above titles.

### Density

medium-high

### Responsive

390px mobile to 2560px+ ultra-wide. Mobile stacks to one column, hides non-essential nav links and secondary table columns, never overflows horizontally. Ultra-wide caps and centres content; only the hero spans 100vw.

### Breakpoints

- **Mobile**: 390px
- **Tablet**: 720px
- **Desktop**: 980px
- **Wide**: 1200px

## Elevation & Depth

### Shadows

- **Carve Sm**: inset 0 1px 2px rgba(36,28,20,.14)
- **Carve Md**: inset 0 2px 6px rgba(36,28,20,.18), inset 0 0 0 1px rgba(36,28,20,.06)
- **Stamp**: inset 0 2px 0 rgba(143,27,22,.45), inset 0 -2px 0 rgba(0,0,0,.10)
- **Stone**: 6px 6px 0 rgba(36,28,20,.10)

## Shapes

### Rounded

- **None**: `0px`
- **Sm**: `0px`
- **Md**: `0px`
- **Lg**: `0px`
- **Full**: `0px`

### Surfaces

- **Treatment**: warm xuan-paper field with subtle CSS fiber speckle and flat cinnabar stamp surfaces
- **Card Style**: surface behind a 3px dark inset stroke (square seal-stone frame) with a hard offset stone-shadow; carved, never floating
- **Bg Pattern**: radial paper-fiber speckle dots via CSS gradients only; no photographic imagery

### Borders

- **Default Width**: 3px
- **Accent Width**: 3px
- **Style**: solid as inset stroke
- **Character**: square seal-stone frames realised as inset box-shadow strokes; thick cinnabar top rule on data regions; never rounded, never a single accent edge

## Components

### Composition

Build layouts on a square grid module, content capped at 1160-1200px and centred (only the landing hero spans 100vw). Elements align to strong horizontal and vertical axes, like the grid of characters within a seal face. Negative space is active — the uncarved area defines the carved. Group related content behind square dark inset frames that echo a seal stone.

### Hierarchy

Primary emphasis through size and cinnabar red; secondary through serif weight and dark ink; tertiary through muted stone gray. Headings are carved-in: large, dark, Noto Serif SC 900. Body flows like brush annotations. Interactive elements stamp forward like freshly pressed chops.

### Density

Medium-high. Seal compositions pack meaning into square spaces; the UI is structured and information-rich without crowding. Consistent 8px spacing units and inset stone frames separate content zones.

### Signature

The decisive press: every control presses inward via inset/stamp shadows and deepens the cinnabar on activation. Five named patterns — Stamp Button, Seal Badge, Stone Card, Imprint Table, Chop-Mark Divider — each appearing live in the embodiment.

## 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-019efa7c-0b56-7ca3-8c1b-fa224a738f6d/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 Press cinnabar (#C0271F) onto warm xuan-paper for primary actions and emphasis
- Do Keep everything square — radius 0; sharp edges convey authority
- Do Use inset and stamp shadows to carve controls inward, never floating drops
- Do Compose on a strong grid, aligned like characters in a seal face
- Do Make one button clearly primary; keep the rest quieter; share one shape and height
- Do Use seal badges with text or characters, not colour alone, for status
- Do Use Noto Serif SC 900 for headings to evoke the structured strokes of seal script
- Do Reserve seal-gold for authentication and certification marks
- Don't Never round corners — seals are carved from square stone
- Don't Avoid gradients and photographic backgrounds — the field is ink-on-paper abstraction (the swappable hero image excepted)
- Don't Do not use floating soft drop-shadows; prefer inset/offset shadows that carve
- Don't Never mix more than three accents in one component
- Don't Never use pills or circular badges; never a single accent edge on a card
- Don't No emoji or symbol glyphs in copy, markup, or on buttons
- Don't Do not trap navigation in a floating boxed pill

### Accessibility

WCAG AA contrast: cinnabar on paper ~4.6:1, dark ink on paper ~13:1, paper-white on cinnabar ~4.7:1. Focus states use a 2px cinnabar inset ring. Touch targets meet 44px. Colour is never the sole indicator — seal badges carry text or characters. Semantic heading order preserved. prefers-reduced-motion respected.

## Imagery Direction

### Pairs With

cinnabar

### Summary

Imagery is hand-pressed cinnabar seal impressions: bold flat vermilion-red carved strokes stamped onto warm cream xuan-paper, forms emerging from carved negative space, grainy mottled edges with fiber gaps, flat single-color with no gradients, composed on a strong square axis and filling the frame edge to edge.

### Subjects

- cranes over mountain peaks
- leaping carp
- auspicious clouds
- pine and rock
- scrolls and chops
- heritage motifs

### Usage

One full-bleed cinnabar impression as the landing hero (swapped via --hero-image); compact chops for features and avatars; sparser half-inked impressions for empty states.

```json
{
  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
  "name": "zhuwen",
  "type": "registry:theme",
  "title": "Zhuwen shadcn Theme",
  "cssVars": {
    "theme": {},
    "light": {
      "background": "#F1E7D2",
      "foreground": "#241C14",
      "card": "#FBF4E3",
      "card-foreground": "#241C14",
      "popover": "#FBF4E3",
      "popover-foreground": "#241C14",
      "primary": "#C0271F",
      "primary-foreground": "#ffffff",
      "secondary": "#241C14",
      "secondary-foreground": "#ffffff",
      "muted": "#756A55",
      "muted-foreground": "#241C14",
      "accent": "#C0271F",
      "accent-foreground": "#ffffff",
      "destructive": "#A8201A",
      "border": "#D8CBAE",
      "input": "#D8CBAE",
      "ring": "#C0271F",
      "chart-1": "#C0271F",
      "chart-2": "#241C14",
      "chart-3": "#C0271F",
      "chart-4": "#4F6B34",
      "chart-5": "#9A6A1E",
      "sidebar": "#FBF4E3",
      "sidebar-foreground": "#241C14",
      "sidebar-primary": "#C0271F",
      "sidebar-primary-foreground": "#ffffff",
      "sidebar-accent": "#355A78",
      "sidebar-accent-foreground": "#ffffff",
      "sidebar-border": "#D8CBAE",
      "sidebar-ring": "#C0271F",
      "radius": "0px"
    },
    "dark": {
      "background": "#0f1115",
      "foreground": "#f8fafc",
      "card": "#181b22",
      "card-foreground": "#f8fafc",
      "popover": "#181b22",
      "popover-foreground": "#f8fafc",
      "primary": "#C0271F",
      "primary-foreground": "#ffffff",
      "secondary": "#252a33",
      "secondary-foreground": "#f8fafc",
      "muted": "#252a33",
      "muted-foreground": "#a1a1aa",
      "accent": "#C0271F",
      "accent-foreground": "#ffffff",
      "destructive": "#A8201A",
      "border": "#303642",
      "input": "#303642",
      "ring": "#C0271F",
      "chart-1": "#C0271F",
      "chart-2": "#241C14",
      "chart-3": "#C0271F",
      "chart-4": "#4F6B34",
      "chart-5": "#9A6A1E",
      "sidebar": "#181b22",
      "sidebar-foreground": "#f8fafc",
      "sidebar-primary": "#C0271F",
      "sidebar-primary-foreground": "#ffffff",
      "sidebar-accent": "#C0271F",
      "sidebar-accent-foreground": "#ffffff",
      "sidebar-border": "#303642",
      "sidebar-ring": "#C0271F",
      "radius": "0px"
    }
  },
  "meta": {
    "source": "katagami",
    "languageId": "en-019efa7c-0b56-7ca3-8c1b-fa224a738f6d",
    "slug": "zhuwen",
    "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": {
      "colors": [
        "accent",
        "accent_deep",
        "bg",
        "border",
        "error",
        "gold",
        "info",
        "muted",
        "on_accent",
        "primary",
        "secondary",
        "success",
        "surface",
        "surface_2",
        "text",
        "warning"
      ],
      "typography": [
        "base_size",
        "body_font",
        "google_fonts_url",
        "heading_font",
        "heading_transform",
        "heading_weight",
        "letter_spacing",
        "line_height",
        "mono_font"
      ],
      "radii": [
        "full",
        "lg",
        "md",
        "none",
        "sm"
      ],
      "shadows": [
        "carve_md",
        "carve_sm",
        "stamp",
        "stone"
      ],
      "spacing": [
        "base",
        "scale"
      ],
      "surfaces": [
        "bg_pattern",
        "card_style",
        "treatment"
      ],
      "borders": [
        "accent_width",
        "character",
        "default_width",
        "style"
      ],
      "motion": [
        "duration",
        "easing",
        "philosophy"
      ]
    }
  }
}
```