A portable design language for agents: download the markdown first, then inspect the preview, tokens, and rules as needed.
Published
Download DESIGN.md
Portable DESIGN.md source of truth for most agents and apps.
the spec
specification
philosophy
summary
Stylus is a recorder language: it treats software the way a strip-chart recorder treats an incoming radio downlink. One pen inks the live signal, continuously, onto a moving ribbon of warm paper ruled with time; you read what a channel just said by looking behind the pen. A parallel reading of the broadcast-control brief, not a recolour of a dark mission-control room — the surface is warm signal-paper, the signal is laid out as horizontal recorder lanes, and the live carriage sweep is the one moving part. One channel, one pen, one live colour; everything else holds in graphite.
values
one live colour: the recorder pen is the only colour on screen, everything else is graphitethe trace is the instrument: ruling, carriage and pen replace gauges, rings and HUD ornamentmake silence visible: quiet channels flatline, locked channels hold a steady marktimecoded truth: captions, cue numbers and channel IDs are primary interface materialpaper, not screen: a warm signal-paper ground ruled with time is the deliberate identity leverthe present is a line: a single vertical carriage marks now and carries the only motion on the page
anti-values
×recolouring to a dark control-room 16:9 viewport with a single orbital arc — that is the other interpretation of the brief×gauges, rings, circular HUD ornament, or meaningless decoration around empty fields×vermilion used as a general brand wash instead of a single live recorder-pen state×rounded marketing cards, nested chrome, boxed nav, or borders used as decoration
Warm signal-paper ground ruled with fine horizontal time lines (24px) and faint vertical timing ticks (48px), like a seismograph drum; never grungy.
card style
No rounded cards: information lives in recorder lanes, channel registers, telemetry readouts, cue logs and side rails, separated by hairline rings and the ruling rather than borders.
treatment
Lifted warm-paper planes with hairline off-white rings as structure, time-rule line texture, an inked graphite waveform, and one vermilion recorder-pen mark per view.
borders4 items
default width
1px
accent width
2px
style
solid
character
Separation is a hairline ring at low opacity, never a decorative or single-edge border; the only 2px line is the vermilion carriage / cue underline marking the live state.
motion3 items
duration
720ms
easing
cubic-bezier(.22,0,.12,1)
philosophy
The carriage sweeps; everything else stays still — slow relay behaviour. The fully settled state renders with no JavaScript; reveal motion is layered behind an .anim class the script sets on <html>, and the carriage animation respects prefers-reduced-motion.
rules
composition
Lay the signal out as stacked horizontal recorder lanes on a warm paper ground ruled with time. One live channel dominates while others flatline or drift; a single vertical carriage marks the present on every lane and ends in a pen dot at the trace. Separate with hairline rings and ruling, never borders or rounded cards; keep the nav open across the header.
hierarchy
Primary hierarchy comes from the inked trace and the carriage, then Space Grotesk headings, then compact Space Mono channel IDs and timecodes, then Archivo body and captions. Active states are marked by a single vermilion pen dot, carriage, or cue underline — never by scale or colour flooding.
density
Alternate quiet paper fields with dense recorder lanes and telemetry strips: flatlined channels and 96-128px atmospheric margins against 8px Space Mono telemetry clusters and tightly ruled lanes.
signature
Carriage now-line: a thin vertical sweep marking the present on every lane, terminating in a small vermilion pen dot at the trace, carrying the only motion on the page.Time-rule paper: fine horizontal ruling lines and faint vertical timing ticks as the ground texture, drawn with repeating-linear-gradient — a seismograph drum, not a card.Inked trace: the signal as an SVG waveform in graphite, with one vermilion segment under the live pen; quiet channels flatline, locked channels hold a steady mark.Channel register: channels stacked as recorder lanes and as a register list, each with its own pen state (recording, drift, lock, idle), never a grid of equal cards.Cue underline: the current timecoded caption carries a single vermilion underline (inset box-shadow); every other cue stays graphite.
layout
grid
Contained max-width 1320-1480px with a generous warm-paper field; recorder lanes span the content width, the dashboard adds a 320px perimeter rail, and only the landing hero spans 100vw.
whitespace
Extreme spacing contrast: 8px telemetry clusters and tightly ruled lanes against 96-128px quiet paper fields and atmospheric section margins, always padding above titles.
density
Medium-high density inside recorder lanes and telemetry strips, with deliberately quiet flatlined channels and wide paper margins so silence reads as intentional.
responsive
Lanes keep their ruling and carriage at every width; stacks collapse to a single column on mobile, side rails move below the lane wall, and nothing overflows horizontally.
breakpoints
mobile
0-639px single-column lanes, hero veil switches to vertical, non-essential nav hidden, telemetry one-up
tablet
640-1023px two-up telemetry, lanes full width, side rail moves below
desktop
1024px+ full lane wall with perimeter rail and full-viewport hero
guidance
do
Keep one live colour on screen and hold everything else in graphite.
Draw the carriage and the ruling as interface structure, not ornament.
Let quiet channels flatline so silence is visible; let locked channels hold a steady mark.
Treat timecodes, cue numbers and channel IDs as primary, legible material.
Separate with hairline rings, ruling, and space; keep the nav open across the header.
Make one button clearly primary in the vermilion pen colour; keep the rest quiet.
avoid
Do not recolour to a dark control-room 16:9 viewport with an orbital arc — that is the other interpretation.
Do not add gauges, rings or HUD ornament; the trace is the instrument.
Do not make vermilion a general brand wash; it is a single live recorder-pen state.
Do not round corners except a pen dot, nest cards, or box the nav in a pill.
Do not let captions become decorative lorem; every cue is timecoded and meaningful.
imagery
pairs with
downlink
summary
A still frame pulled off a broadcast-safe feed in lifted graphite grayscale, applied to recorder and signal-paper subjects: a strip-chart stylus inking a trace, a seismograph drum, a ribbon of time-ruled paper, with one narrow vermilion recorder-pen line as the only colour.
subjects
a strip-chart recorder stylus inking a waveform onto moving papera seismograph drum and pena ribbon of time-ruled signal papera chromed recording carriage poised mid-sweep
usage
Use for the landing hero and section imagery: full-frame, broadcast-safe grayscale, time-rule ground, one vermilion ink trace, no text. Never illustrate the thumbnail (that comes from the embodiment).
katagami spec
# Stylus
## Philosophy
Stylus is a recorder language: it treats software the way a strip-chart recorder treats an incoming radio downlink. One pen inks the live signal, continuously, onto a moving ribbon of warm paper ruled with time; you read what a channel just said by looking behind the pen. A parallel reading of the broadcast-control brief, not a recolour of a dark mission-control room — the surface is warm signal-paper, the signal is laid out as horizontal recorder lanes, and the live carriage sweep is the one moving part. One channel, one pen, one live colour; everything else holds in graphite.
### Values
- one live colour: the recorder pen is the only colour on screen, everything else is graphite
- the trace is the instrument: ruling, carriage and pen replace gauges, rings and HUD ornament
- make silence visible: quiet channels flatline, locked channels hold a steady mark
- timecoded truth: captions, cue numbers and channel IDs are primary interface material
- paper, not screen: a warm signal-paper ground ruled with time is the deliberate identity lever
- the present is a line: a single vertical carriage marks now and carries the only motion on the page
### Anti-Values
- recolouring to a dark control-room 16:9 viewport with a single orbital arc — that is the other interpretation of the brief
- gauges, rings, circular HUD ornament, or meaningless decoration around empty fields
- vermilion used as a general brand wash instead of a single live recorder-pen state
- rounded marketing cards, nested chrome, boxed nav, or borders used as decoration
### Visual Character
- Warm signal-paper ground ruled with fine horizontal time lines and faint vertical timing ticks, like a seismograph drum rather than a card surface.
- Channels are laid out as stacked horizontal recorder lanes; the signal is an inked SVG waveform in graphite with one vermilion segment under the live pen.
- A single thin vertical carriage marks the present on every lane, terminating in a small vermilion pen dot where it meets the trace, and carries the only motion on the page.
- Timecoded cue captions and compact Space Mono channel IDs are primary material; the current cue carries one vermilion underline while every other state stays graphite.
- Separation comes from hairline rings, the ruling, and generous space — no decorative borders, no nested cards, no boxed nav; corners are square except a pen dot.
## Tokens
### Colors
| Name | Value |
|------|-------|
| bg | `#EDE7DA` |
| surface | `#F6F2E8` |
| surface_2 | `#E3DCCB` |
| rail | `#DCD4C2` |
| text | `#23211C` |
| text_strong | `#16140F` |
| muted | `#7A746A` |
| secondary | `#918B7F` |
| guide | `#C8C0AE` |
| accent | `#D6502A` |
| accent_soft | `#E8A188` |
| on_accent | `#F6F2E8` |
| border | `rgba(35,33,28,0.14)` |
| success | `#5E7A4E` |
| warning | `#C58A2E` |
| error | `#B23A2A` |
| info | `#5E7488` |
### Typography
- **Base Size**: 17px
- **Body Font**: Archivo
- **Heading Font**: Space Grotesk
- **Mono Font**: Space Mono
- **Heading Weight**: 600
- **Heading Transform**: none
- **Letter Spacing**: -0.01em
- **Display Letter Spacing**: -0.03em
- **Line Height**: 1.55
- **Scale Ratio**: 1.2
- **Google Fonts Url**: https://fonts.googleapis.com/css2?family=Space+Grotesk:wght@400;500;600;700&family=Archivo:wght@400;500;600;700&family=Space+Mono:wght@400;700&display=swap
### Radii
- **None**: 0px
- **Sm**: 0px
- **Md**: 0px
- **Lg**: 0px
- **Full**: 9999px
### Shadows
- **Sm**: none
- **Md**: 0 0 0 1px rgba(35,33,28,0.08)
- **Lg**: 0 24px 60px rgba(35,33,28,0.14)
### Spacing
- **Base**: 8px
- **Scale**: [4,8,12,16,24,32,48,64,96,128]
### Surfaces
- **Bg Pattern**: Warm signal-paper ground ruled with fine horizontal time lines (24px) and faint vertical timing ticks (48px), like a seismograph drum; never grungy.
- **Card Style**: No rounded cards: information lives in recorder lanes, channel registers, telemetry readouts, cue logs and side rails, separated by hairline rings and the ruling rather than borders.
- **Treatment**: Lifted warm-paper planes with hairline off-white rings as structure, time-rule line texture, an inked graphite waveform, and one vermilion recorder-pen mark per view.
### Borders
- **Default Width**: 1px
- **Accent Width**: 2px
- **Style**: solid
- **Character**: Separation is a hairline ring at low opacity, never a decorative or single-edge border; the only 2px line is the vermilion carriage / cue underline marking the live state.
### Motion
- **Duration**: 720ms
- **Easing**: cubic-bezier(.22,0,.12,1)
- **Philosophy**: The carriage sweeps; everything else stays still — slow relay behaviour. The fully settled state renders with no JavaScript; reveal motion is layered behind an .anim class the script sets on <html>, and the carriage animation respects prefers-reduced-motion.
## Rules
### Composition
Lay the signal out as stacked horizontal recorder lanes on a warm paper ground ruled with time. One live channel dominates while others flatline or drift; a single vertical carriage marks the present on every lane and ends in a pen dot at the trace. Separate with hairline rings and ruling, never borders or rounded cards; keep the nav open across the header.
### Hierarchy
Primary hierarchy comes from the inked trace and the carriage, then Space Grotesk headings, then compact Space Mono channel IDs and timecodes, then Archivo body and captions. Active states are marked by a single vermilion pen dot, carriage, or cue underline — never by scale or colour flooding.
### Density
Alternate quiet paper fields with dense recorder lanes and telemetry strips: flatlined channels and 96-128px atmospheric margins against 8px Space Mono telemetry clusters and tightly ruled lanes.
### Signature
- Carriage now-line: a thin vertical sweep marking the present on every lane, terminating in a small vermilion pen dot at the trace, carrying the only motion on the page.
- Time-rule paper: fine horizontal ruling lines and faint vertical timing ticks as the ground texture, drawn with repeating-linear-gradient — a seismograph drum, not a card.
- Inked trace: the signal as an SVG waveform in graphite, with one vermilion segment under the live pen; quiet channels flatline, locked channels hold a steady mark.
- Channel register: channels stacked as recorder lanes and as a register list, each with its own pen state (recording, drift, lock, idle), never a grid of equal cards.
- Cue underline: the current timecoded caption carries a single vermilion underline (inset box-shadow); every other cue stays graphite.
## Layout
### Grid
Contained max-width 1320-1480px with a generous warm-paper field; recorder lanes span the content width, the dashboard adds a 320px perimeter rail, and only the landing hero spans 100vw.
### Whitespace
Extreme spacing contrast: 8px telemetry clusters and tightly ruled lanes against 96-128px quiet paper fields and atmospheric section margins, always padding above titles.
### Density
Medium-high density inside recorder lanes and telemetry strips, with deliberately quiet flatlined channels and wide paper margins so silence reads as intentional.
### Responsive
Lanes keep their ruling and carriage at every width; stacks collapse to a single column on mobile, side rails move below the lane wall, and nothing overflows horizontally.
### Breakpoints
- **Mobile**: 0-639px single-column lanes, hero veil switches to vertical, non-essential nav hidden, telemetry one-up
- **Tablet**: 640-1023px two-up telemetry, lanes full width, side rail moves below
- **Desktop**: 1024px+ full lane wall with perimeter rail and full-viewport hero
## Guidance
### Do
- Keep one live colour on screen and hold everything else in graphite.
- Draw the carriage and the ruling as interface structure, not ornament.
- Let quiet channels flatline so silence is visible; let locked channels hold a steady mark.
- Treat timecodes, cue numbers and channel IDs as primary, legible material.
- Separate with hairline rings, ruling, and space; keep the nav open across the header.
- Make one button clearly primary in the vermilion pen colour; keep the rest quiet.
### Don't
- Do not recolour to a dark control-room 16:9 viewport with an orbital arc — that is the other interpretation.
- Do not add gauges, rings or HUD ornament; the trace is the instrument.
- Do not make vermilion a general brand wash; it is a single live recorder-pen state.
- Do not round corners except a pen dot, nest cards, or box the nav in a pill.
- Do not let captions become decorative lorem; every cue is timecoded and meaningful.
### Accessibility
Maintain strong contrast between warm graphite ink and paper, keep cue captions and timecodes at readable sizes, label every pen state with text beside the vermilion mark, style every form control explicitly, render the settled state with no JavaScript, and respect prefers-reduced-motion for the carriage sweep.
## Imagery Direction
### Pairs With
downlink
### Summary
A still frame pulled off a broadcast-safe feed in lifted graphite grayscale, applied to recorder and signal-paper subjects: a strip-chart stylus inking a trace, a seismograph drum, a ribbon of time-ruled paper, with one narrow vermilion recorder-pen line as the only colour.
### Subjects
- a strip-chart recorder stylus inking a waveform onto moving paper
- a seismograph drum and pen
- a ribbon of time-ruled signal paper
- a chromed recording carriage poised mid-sweep
### Usage
Use for the landing hero and section imagery: full-frame, broadcast-safe grayscale, time-rule ground, one vermilion ink trace, no text. Never illustrate the thumbnail (that comes from the embodiment).
DESIGN.md
---
version: "alpha"
name: "Stylus"
description: "Agent-curated design language exported from Katagami as DESIGN.md."
colors:
bg: "#EDE7DA"
surface: "#F6F2E8"
surface_2: "#E3DCCB"
rail: "#DCD4C2"
text: "#23211C"
text_strong: "#16140F"
muted: "#7A746A"
secondary: "#918B7F"
guide: "#C8C0AE"
accent: "#D6502A"
accent_soft: "#E8A188"
on_accent: "#F6F2E8"
success: "#5E7A4E"
warning: "#C58A2E"
error: "#B23A2A"
info: "#5E7488"
typography:
headline-lg:
fontFamily: "Space Grotesk"
fontSize: "1.836rem"
fontWeight: 700
lineHeight: 1.1
letterSpacing: "-0.01em"
headline-md:
fontFamily: "Space Grotesk"
fontSize: "1.53rem"
fontWeight: 600
lineHeight: 1.15
letterSpacing: "-0.01em"
body-md:
fontFamily: "Archivo"
fontSize: "17px"
fontWeight: 400
lineHeight: 1.55
letterSpacing: "-0.01em"
label-md:
fontFamily: "Space Mono"
fontSize: "0.75rem"
fontWeight: 600
lineHeight: 1
letterSpacing: "0.08em"
rounded:
none: "0px"
sm: "0px"
md: "0px"
lg: "0px"
full: "9999px"
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-rail:
backgroundColor: "{colors.rail}"
color-reference-text:
backgroundColor: "{colors.text}"
color-reference-text_strong:
backgroundColor: "{colors.text_strong}"
color-reference-muted:
backgroundColor: "{colors.muted}"
color-reference-secondary:
backgroundColor: "{colors.secondary}"
color-reference-guide:
backgroundColor: "{colors.guide}"
color-reference-accent:
backgroundColor: "{colors.accent}"
color-reference-accent_soft:
backgroundColor: "{colors.accent_soft}"
color-reference-on_accent:
backgroundColor: "{colors.on_accent}"
color-reference-success:
backgroundColor: "{colors.success}"
color-reference-warning:
backgroundColor: "{colors.warning}"
color-reference-error:
backgroundColor: "{colors.error}"
color-reference-info:
backgroundColor: "{colors.info}"
button-primary:
backgroundColor: "{colors.accent}"
textColor: "#000000"
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"
---
# Stylus
## Overview
Stylus is a recorder language: it treats software the way a strip-chart recorder treats an incoming radio downlink. One pen inks the live signal, continuously, onto a moving ribbon of warm paper ruled with time; you read what a channel just said by looking behind the pen. A parallel reading of the broadcast-control brief, not a recolour of a dark mission-control room — the surface is warm signal-paper, the signal is laid out as horizontal recorder lanes, and the live carriage sweep is the one moving part. One channel, one pen, one live colour; everything else holds in graphite.
### Values
- one live colour: the recorder pen is the only colour on screen, everything else is graphite
- the trace is the instrument: ruling, carriage and pen replace gauges, rings and HUD ornament
- make silence visible: quiet channels flatline, locked channels hold a steady mark
- timecoded truth: captions, cue numbers and channel IDs are primary interface material
- paper, not screen: a warm signal-paper ground ruled with time is the deliberate identity lever
- the present is a line: a single vertical carriage marks now and carries the only motion on the page
### Anti-Values
- recolouring to a dark control-room 16:9 viewport with a single orbital arc — that is the other interpretation of the brief
- gauges, rings, circular HUD ornament, or meaningless decoration around empty fields
- vermilion used as a general brand wash instead of a single live recorder-pen state
- rounded marketing cards, nested chrome, boxed nav, or borders used as decoration
### Visual Character
- Warm signal-paper ground ruled with fine horizontal time lines and faint vertical timing ticks, like a seismograph drum rather than a card surface.
- Channels are laid out as stacked horizontal recorder lanes; the signal is an inked SVG waveform in graphite with one vermilion segment under the live pen.
- A single thin vertical carriage marks the present on every lane, terminating in a small vermilion pen dot where it meets the trace, and carries the only motion on the page.
- Timecoded cue captions and compact Space Mono channel IDs are primary material; the current cue carries one vermilion underline while every other state stays graphite.
- Separation comes from hairline rings, the ruling, and generous space — no decorative borders, no nested cards, no boxed nav; corners are square except a pen dot.
## 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 | `#EDE7DA` |
| surface | `#F6F2E8` |
| surface_2 | `#E3DCCB` |
| rail | `#DCD4C2` |
| text | `#23211C` |
| text_strong | `#16140F` |
| muted | `#7A746A` |
| secondary | `#918B7F` |
| guide | `#C8C0AE` |
| accent | `#D6502A` |
| accent_soft | `#E8A188` |
| on_accent | `#F6F2E8` |
| success | `#5E7A4E` |
| warning | `#C58A2E` |
| error | `#B23A2A` |
| info | `#5E7488` |
## Typography
- **Headline-Lg**: Space Grotesk, 1.836rem, weight 700, line-height 1.1.
- **Headline-Md**: Space Grotesk, 1.53rem, weight 600, line-height 1.15.
- **Body-Md**: Archivo, 17px, weight 400, line-height 1.55.
- **Label-Md**: Space 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**: `48px`
- **4xl**: `64px`
- **Step-8**: `96px`
- **Step-9**: `128px`
### Grid
Contained max-width 1320-1480px with a generous warm-paper field; recorder lanes span the content width, the dashboard adds a 320px perimeter rail, and only the landing hero spans 100vw.
### Whitespace
Extreme spacing contrast: 8px telemetry clusters and tightly ruled lanes against 96-128px quiet paper fields and atmospheric section margins, always padding above titles.
### Density
Medium-high density inside recorder lanes and telemetry strips, with deliberately quiet flatlined channels and wide paper margins so silence reads as intentional.
### Responsive
Lanes keep their ruling and carriage at every width; stacks collapse to a single column on mobile, side rails move below the lane wall, and nothing overflows horizontally.
### Breakpoints
- **Mobile**: 0-639px single-column lanes, hero veil switches to vertical, non-essential nav hidden, telemetry one-up
- **Tablet**: 640-1023px two-up telemetry, lanes full width, side rail moves below
- **Desktop**: 1024px+ full lane wall with perimeter rail and full-viewport hero
## Elevation & Depth
### Shadows
- **Sm**: none
- **Md**: 0 0 0 1px rgba(35,33,28,0.08)
- **Lg**: 0 24px 60px rgba(35,33,28,0.14)
## Shapes
### Rounded
- **None**: `0px`
- **Sm**: `0px`
- **Md**: `0px`
- **Lg**: `0px`
- **Full**: `9999px`
### Surfaces
- **Bg Pattern**: Warm signal-paper ground ruled with fine horizontal time lines (24px) and faint vertical timing ticks (48px), like a seismograph drum; never grungy.
- **Card Style**: No rounded cards: information lives in recorder lanes, channel registers, telemetry readouts, cue logs and side rails, separated by hairline rings and the ruling rather than borders.
- **Treatment**: Lifted warm-paper planes with hairline off-white rings as structure, time-rule line texture, an inked graphite waveform, and one vermilion recorder-pen mark per view.
### Borders
- **Default Width**: 1px
- **Accent Width**: 2px
- **Style**: solid
- **Character**: Separation is a hairline ring at low opacity, never a decorative or single-edge border; the only 2px line is the vermilion carriage / cue underline marking the live state.
## Components
### Composition
Lay the signal out as stacked horizontal recorder lanes on a warm paper ground ruled with time. One live channel dominates while others flatline or drift; a single vertical carriage marks the present on every lane and ends in a pen dot at the trace. Separate with hairline rings and ruling, never borders or rounded cards; keep the nav open across the header.
### Hierarchy
Primary hierarchy comes from the inked trace and the carriage, then Space Grotesk headings, then compact Space Mono channel IDs and timecodes, then Archivo body and captions. Active states are marked by a single vermilion pen dot, carriage, or cue underline — never by scale or colour flooding.
### Density
Alternate quiet paper fields with dense recorder lanes and telemetry strips: flatlined channels and 96-128px atmospheric margins against 8px Space Mono telemetry clusters and tightly ruled lanes.
### Signature
- Carriage now-line: a thin vertical sweep marking the present on every lane, terminating in a small vermilion pen dot at the trace, carrying the only motion on the page.
- Time-rule paper: fine horizontal ruling lines and faint vertical timing ticks as the ground texture, drawn with repeating-linear-gradient — a seismograph drum, not a card.
- Inked trace: the signal as an SVG waveform in graphite, with one vermilion segment under the live pen; quiet channels flatline, locked channels hold a steady mark.
- Channel register: channels stacked as recorder lanes and as a register list, each with its own pen state (recording, drift, lock, idle), never a grid of equal cards.
- Cue underline: the current timecoded caption carries a single vermilion underline (inset box-shadow); every other cue stays graphite.
## 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-019ef94d-a6b4-7102-8d3b-01adf7b3ddcb/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 one live colour on screen and hold everything else in graphite.
- Do Draw the carriage and the ruling as interface structure, not ornament.
- Do Let quiet channels flatline so silence is visible; let locked channels hold a steady mark.
- Do Treat timecodes, cue numbers and channel IDs as primary, legible material.
- Do Separate with hairline rings, ruling, and space; keep the nav open across the header.
- Do Make one button clearly primary in the vermilion pen colour; keep the rest quiet.
- Don't Do not recolour to a dark control-room 16:9 viewport with an orbital arc — that is the other interpretation.
- Don't Do not add gauges, rings or HUD ornament; the trace is the instrument.
- Don't Do not make vermilion a general brand wash; it is a single live recorder-pen state.
- Don't Do not round corners except a pen dot, nest cards, or box the nav in a pill.
- Don't Do not let captions become decorative lorem; every cue is timecoded and meaningful.
### Accessibility
Maintain strong contrast between warm graphite ink and paper, keep cue captions and timecodes at readable sizes, label every pen state with text beside the vermilion mark, style every form control explicitly, render the settled state with no JavaScript, and respect prefers-reduced-motion for the carriage sweep.
## Imagery Direction
### Pairs With
downlink
### Summary
A still frame pulled off a broadcast-safe feed in lifted graphite grayscale, applied to recorder and signal-paper subjects: a strip-chart stylus inking a trace, a seismograph drum, a ribbon of time-ruled paper, with one narrow vermilion recorder-pen line as the only colour.
### Subjects
- a strip-chart recorder stylus inking a waveform onto moving paper
- a seismograph drum and pen
- a ribbon of time-ruled signal paper
- a chromed recording carriage poised mid-sweep
### Usage
Use for the landing hero and section imagery: full-frame, broadcast-safe grayscale, time-rule ground, one vermilion ink trace, no text. Never illustrate the thumbnail (that comes from the embodiment).
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.
# Stylus shadcn/ui Components
Artifact: `component-recipes-v1`
Author: `katagami-ui-projection`
Language ID: `en-019ef94d-a6b4-7102-8d3b-01adf7b3ddcb`
Slug: `stylus`
## Intent
Stylus is a recorder language: it treats software the way a strip-chart recorder treats an incoming radio downlink. One pen inks the live signal, continuously, onto a moving ribbon of warm paper ruled with time; you read what a channel just said by looking behind the pen. A parallel reading of the broadcast-control brief, not a recolour of a dark mission-control room — the surface is warm signal-paper, the signal is laid out as horizontal recorder lanes, and the live carriage sweep is the one moving part. One channel, one pen, one live colour; everything else holds in graphite.
## 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:
{
"bg": "#EDE7DA",
"surface": "#F6F2E8",
"surface_2": "#E3DCCB",
"rail": "#DCD4C2",
"text": "#23211C",
"text_strong": "#16140F",
"muted": "#7A746A",
"secondary": "#918B7F",
"guide": "#C8C0AE",
"accent": "#D6502A",
"accent_soft": "#E8A188",
"on_accent": "#F6F2E8",
"border": "rgba(35,33,28,0.14)",
"success": "#5E7A4E",
"warning": "#C58A2E",
"error": "#B23A2A",
"info": "#5E7488"
}
Typography:
{
"base_size": "17px",
"body_font": "Archivo",
"heading_font": "Space Grotesk",
"mono_font": "Space Mono",
"heading_weight": "600",
"heading_transform": "none",
"letter_spacing": "-0.01em",
"display_letter_spacing": "-0.03em",
"line_height": 1.55,
"scale_ratio": 1.2,
"google_fonts_url": "https://fonts.googleapis.com/css2?family=Space+Grotesk:wght@400;500;600;700&family=Archivo:wght@400;500;600;700&family=Space+Mono:wght@400;700&display=swap"
}
## Visual character to preserve
- Warm signal-paper ground ruled with fine horizontal time lines and faint vertical timing ticks, like a seismograph drum rather than a card surface.
- Channels are laid out as stacked horizontal recorder lanes; the signal is an inked SVG waveform in graphite with one vermilion segment under the live pen.
- A single thin vertical carriage marks the present on every lane, terminating in a small vermilion pen dot where it meets the trace, and carries the only motion on the page.
- Timecoded cue captions and compact Space Mono channel IDs are primary material; the current cue carries one vermilion underline while every other state stays graphite.
- Separation comes from hairline rings, the ruling, and generous space — no decorative borders, no nested cards, no boxed nav; corners are square except a pen dot.
## ShadSync visual profile
{
"family": "paper-collage",
"material": "paper",
"contour": "default",
"border": "solid",
"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/stylus/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 one live colour on screen and hold everything else in graphite.; Draw the carriage and the ruling as interface structure, not ornament.; Let quiet channels flatline so silence is visible; let locked channels hold a steady mark.; Treat timecodes, cue numbers and channel IDs as primary, legible material.; Separate with hairline rings, ruling, and space; keep the nav open across the header.; Make one button clearly primary in the vermilion pen colour; keep the rest quiet.
- Do not: Do not recolour to a dark control-room 16:9 viewport with an orbital arc — that is the other interpretation.; Do not add gauges, rings or HUD ornament; the trace is the instrument.; Do not make vermilion a general brand wash; it is a single live recorder-pen state.; Do not round corners except a pen dot, nest cards, or box the nav in a pill.; Do not let captions become decorative lorem; every cue is timecoded and meaningful.
## 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 StylusShadcnKit() {
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">Stylus</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
{
"grid": "Contained max-width 1320-1480px with a generous warm-paper field; recorder lanes span the content width, the dashboard adds a 320px perimeter rail, and only the landing hero spans 100vw.",
"whitespace": "Extreme spacing contrast: 8px telemetry clusters and tightly ruled lanes against 96-128px quiet paper fields and atmospheric section margins, always padding above titles.",
"density": "Medium-high density inside recorder lanes and telemetry strips, with deliberately quiet flatlined channels and wide paper margins so silence reads as intentional.",
"responsive": "Lanes keep their ruling and carriage at every width; stacks collapse to a single column on mobile, side rails move below the lane wall, and nothing overflows horizontally.",
"breakpoints": {
"mobile": "0-639px single-column lanes, hero veil switches to vertical, non-essential nav hidden, telemetry one-up",
"tablet": "640-1023px two-up telemetry, lanes full width, side rail moves below",
"desktop": "1024px+ full lane wall with perimeter rail and full-viewport hero"
}
}
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-019ef94d-a6b4-7102-8d3b-01adf7b3ddcb",
"name": "Stylus",
"slug": "stylus"
},
"installCommand": "npx shadcn@latest add button card input textarea select dialog sheet tabs badge separator checkbox switch slider tooltip dropdown-menu table",
"primitives": [
"button",
"card",
"input",
"textarea",
"select",
"dialog",
"sheet",
"tabs",
"badge",
"separator",
"checkbox",
"switch",
"slider",
"tooltip",
"dropdown-menu",
"table"
],
"identityNotes": [
"Warm signal-paper ground ruled with fine horizontal time lines and faint vertical timing ticks, like a seismograph drum rather than a card surface.",
"Channels are laid out as stacked horizontal recorder lanes; the signal is an inked SVG waveform in graphite with one vermilion segment under the live pen.",
"A single thin vertical carriage marks the present on every lane, terminating in a small vermilion pen dot where it meets the trace, and carries the only motion on the page.",
"Timecoded cue captions and compact Space Mono channel IDs are primary material; the current cue carries one vermilion underline while every other state stays graphite.",
"Separation comes from hairline rings, the ruling, and generous space — no decorative borders, no nested cards, no boxed nav; corners are square except a pen dot."
],
"visualProfile": {
"family": "paper-collage",
"material": "paper",
"contour": "default",
"border": "solid",
"underlay": false,
"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": "Stylus 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 one live colour on screen and hold everything else in graphite.",
"Draw the carriage and the ruling as interface structure, not ornament.",
"Let quiet channels flatline so silence is visible; let locked channels hold a steady mark.",
"Treat timecodes, cue numbers and channel IDs as primary, legible material.",
"Separate with hairline rings, ruling, and space; keep the nav open across the header.",
"Make one button clearly primary in the vermilion pen colour; keep the rest quiet."
],
"dont": [
"Do not recolour to a dark control-room 16:9 viewport with an orbital arc — that is the other interpretation.",
"Do not add gauges, rings or HUD ornament; the trace is the instrument.",
"Do not make vermilion a general brand wash; it is a single live recorder-pen state.",
"Do not round corners except a pen dot, nest cards, or box the nav in a pill.",
"Do not let captions become decorative lorem; every cue is timecoded and meaningful."
]
}
}