design language·quiet-techni

Quiet High-Contrast Technical Reader

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

Draft

Download DESIGN.md

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

the spec

specification

philosophy

summary

Quiet High-Contrast Technical Reader is a light-mode documentation language where the interface recedes behind carefully measured prose: warm near-white surfaces, charcoal text, typographic hierarchy, generous margins, and one restrained highlighter accent for interaction and emphasis.

values

Reading endurance over visual novelty.Whitespace as structure rather than decoration.Typographic hierarchy before containers, borders, or chrome.High contrast that feels calm, not harsh.One accent used functionally like a reader's highlighter.

anti-values

×No bordered card grids, heavy dividers, tinted panels, or dashboard furniture.×No multi-accent brand palette, decorative gradients, or saturation competing with prose.×No full-width text measures, cramped line-height, or tiny secondary labels.×No low-contrast gray body copy or link colors that fail accessibility.×No ornament that makes documentation feel like marketing.

tokens

color12 items

accent: #A66A00
accentFocus: #C47A00
accentSoft: #FFF0C2
canvas: #FAFAF7
codeSurface: #F1F1EC
codeText: #20201E
selection: #FFE8A3
surface: #FFFFFF
surfaceSubtle: #F3F3EE
text: #242424
textFaint: #8A877F
textMuted: #66645E

radius3 items

code: 8px
none: 0px
soft: 6px

shadow1 items

none: none

space8 items

lg: 28px
md: 16px
measure: 68ch
pageX: clamp(24px, 7vw, 112px)
sm: 8px
xl: 44px
xs: 4px
xxl: 72px

typography11 items

body: 17px/1.72 400 0em
bodySmall: 15px/1.6 400 0em
caption: 13px/1.45 450 0.01em
code: 14px/1.65 450 0em
display: 40px/1.08 650 -0.025em
fontMono: JetBrains Mono, SFMono-Regular, ui-monospace, Menlo, monospace
fontSans: Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, Segoe UI, sans-serif
fontSerif: Charter, Iowan Old Style, Georgia, serif
section: 22px/1.28 620 -0.012em
subheading: 17px/1.45 650 0em
title: 30px/1.18 650 -0.018em

rules

name: Near-white reading canvas
rule: Default pages to #FAFAF7 or #FFFFFF with charcoal #242424 text; reserve gray surfaces for code, notes, and inactive navigation only.

name: Bounded prose measure
rule: Keep long-form paragraphs around 62-72 characters per line with 1.65-1.75 line-height and generous paragraph spacing.

name: Typographic hierarchy first
rule: Use size, weight, line-height, and spacing to establish title, section, subheading, body, code, and meta roles before adding containers.

name: Single highlighter accent
rule: Use one muted amber accent and its soft tint for links, focus, selection, active TOC entries, and marked search terms; do not add a second decorative accent family.

name: Borderless separation
rule: Avoid visible card borders and rule-heavy layouts; separate regions with whitespace, alignment, subtle background shifts, and type contrast.

name: Readable technical matter
rule: Code blocks, inline code, tables, and callouts must remain high-contrast, scan-friendly, and visually quieter than the prose hierarchy.

layout

breakpoints

Mobile <640px uses 20-24px margins and hides side rails; tablet 641-980px keeps a single reading column; desktop >=981px may reveal a subtle table of contents rail.

density

Low-to-medium density for prose; code and tables may be dense but must be bounded, padded, and surrounded by rest space.

grid

Centered reading column with optional quiet side rail; desktop uses a max content measure near 68ch and page margins from 72px to 112px, while reference pages may use a 12-column shell with prose spanning 6-7 columns.

responsive

Preserve reading order and measure before preserving side navigation. TOC becomes collapsible on small screens; long code scrolls horizontally within a quiet code surface.

whitespace

Vertical whitespace is the primary separator: 56-80px between major sections, 24-36px before subheads, and comfortable paragraph rhythm without visible rules.

guidance

Use #FAFAF7 or white as the dominant canvas with charcoal prose and soft gray metadata.
Limit prose width to roughly 62-72 characters and let side rails breathe rather than filling them.
Use the amber highlighter accent only for links, focus rings, active table-of-contents entries, search matches, selections, and marked terms.
Separate sections with spacing, alignment, indentation, and type contrast instead of lines or boxes.
Give code a quiet paper-gray surface, strong monospace contrast, and enough padding to read without turning into a card.
Make captions, breadcrumbs, and metadata visibly secondary while preserving legibility.

avoid

Do not introduce extra accent colors for status, decoration, illustrations, or charts unless required by content semantics.
Do not wrap every block in bordered cards or rely on horizontal rules for rhythm.
Do not use pure black body copy on pure white if it creates glare; use charcoal on warm near-white.
Do not allow paragraphs, tables, or code samples to run full browser width.
Do not reduce secondary text below readable contrast or size.
Do not make links look like brand badges; they should feel like highlighted reading marks.

katagami spec

# Quiet High-Contrast Technical Reader

## Philosophy

### Values

- Reading endurance over visual novelty.
- Whitespace as structure rather than decoration.
- Typographic hierarchy before containers, borders, or chrome.
- High contrast that feels calm, not harsh.
- One accent used functionally like a reader's highlighter.

### Anti-Values

- No bordered card grids, heavy dividers, tinted panels, or dashboard furniture.
- No multi-accent brand palette, decorative gradients, or saturation competing with prose.
- No full-width text measures, cramped line-height, or tiny secondary labels.
- No low-contrast gray body copy or link colors that fail accessibility.
- No ornament that makes documentation feel like marketing.

## Tokens

### Color

- **Accent**: #A66A00
- **AccentFocus**: #C47A00
- **AccentSoft**: #FFF0C2
- **Canvas**: #FAFAF7
- **CodeSurface**: #F1F1EC
- **CodeText**: #20201E
- **Selection**: #FFE8A3
- **Surface**: #FFFFFF
- **SurfaceSubtle**: #F3F3EE
- **Text**: #242424
- **TextFaint**: #8A877F
- **TextMuted**: #66645E

### Radius

- **Code**: 8px
- **None**: 0px
- **Soft**: 6px

### Shadow

- **None**: none

### Space

- **Lg**: 28px
- **Md**: 16px
- **Measure**: 68ch
- **PageX**: clamp(24px, 7vw, 112px)
- **Sm**: 8px
- **Xl**: 44px
- **Xs**: 4px
- **Xxl**: 72px

### Typography

- **Body**: 17px/1.72 400 0em
- **BodySmall**: 15px/1.6 400 0em
- **Caption**: 13px/1.45 450 0.01em
- **Code**: 14px/1.65 450 0em
- **Display**: 40px/1.08 650 -0.025em
- **FontMono**: JetBrains Mono, SFMono-Regular, ui-monospace, Menlo, monospace
- **FontSans**: Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, Segoe UI, sans-serif
- **FontSerif**: Charter, Iowan Old Style, Georgia, serif
- **Section**: 22px/1.28 620 -0.012em
- **Subheading**: 17px/1.45 650 0em
- **Title**: 30px/1.18 650 -0.018em

## Rules

### 0

- **Name**: Near-white reading canvas
- **Rule**: Default pages to #FAFAF7 or #FFFFFF with charcoal #242424 text; reserve gray surfaces for code, notes, and inactive navigation only.

### 1

- **Name**: Bounded prose measure
- **Rule**: Keep long-form paragraphs around 62-72 characters per line with 1.65-1.75 line-height and generous paragraph spacing.

### 2

- **Name**: Typographic hierarchy first
- **Rule**: Use size, weight, line-height, and spacing to establish title, section, subheading, body, code, and meta roles before adding containers.

### 3

- **Name**: Single highlighter accent
- **Rule**: Use one muted amber accent and its soft tint for links, focus, selection, active TOC entries, and marked search terms; do not add a second decorative accent family.

### 4

- **Name**: Borderless separation
- **Rule**: Avoid visible card borders and rule-heavy layouts; separate regions with whitespace, alignment, subtle background shifts, and type contrast.

### 5

- **Name**: Readable technical matter
- **Rule**: Code blocks, inline code, tables, and callouts must remain high-contrast, scan-friendly, and visually quieter than the prose hierarchy.

## Layout

### Breakpoints

Mobile <640px uses 20-24px margins and hides side rails; tablet 641-980px keeps a single reading column; desktop >=981px may reveal a subtle table of contents rail.

### Density

Low-to-medium density for prose; code and tables may be dense but must be bounded, padded, and surrounded by rest space.

### Grid

Centered reading column with optional quiet side rail; desktop uses a max content measure near 68ch and page margins from 72px to 112px, while reference pages may use a 12-column shell with prose spanning 6-7 columns.

### Responsive

Preserve reading order and measure before preserving side navigation. TOC becomes collapsible on small screens; long code scrolls horizontally within a quiet code surface.

### Whitespace

Vertical whitespace is the primary separator: 56-80px between major sections, 24-36px before subheads, and comfortable paragraph rhythm without visible rules.

## Guidance

### Do

- Use #FAFAF7 or white as the dominant canvas with charcoal prose and soft gray metadata.
- Limit prose width to roughly 62-72 characters and let side rails breathe rather than filling them.
- Use the amber highlighter accent only for links, focus rings, active table-of-contents entries, search matches, selections, and marked terms.
- Separate sections with spacing, alignment, indentation, and type contrast instead of lines or boxes.
- Give code a quiet paper-gray surface, strong monospace contrast, and enough padding to read without turning into a card.
- Make captions, breadcrumbs, and metadata visibly secondary while preserving legibility.

### Don't

- Do not introduce extra accent colors for status, decoration, illustrations, or charts unless required by content semantics.
- Do not wrap every block in bordered cards or rely on horizontal rules for rhythm.
- Do not use pure black body copy on pure white if it creates glare; use charcoal on warm near-white.
- Do not allow paragraphs, tables, or code samples to run full browser width.
- Do not reduce secondary text below readable contrast or size.
- Do not make links look like brand badges; they should feel like highlighted reading marks.

### Accessibility

Body text must exceed WCAG AA 4.5:1 contrast on the near-white canvas; large headings must exceed 3:1. Keep body size near 17px with generous line-height, visible keyboard focus, semantic headings, non-color-only states, and a bounded reading measure.

### Usage Context

Best for documentation, knowledge bases, API references, technical essays, runbooks, research notes, and product education where sustained reading and trust matter more than brand spectacle.

DESIGN.md

---
version: "alpha"
name: "Quiet High-Contrast Technical Reader"
description: "Agent-curated design language exported from Katagami as DESIGN.md."
typography:
headline-lg:
fontFamily: "Inter"
fontSize: "1.953rem"
fontWeight: 700
lineHeight: 1.1
letterSpacing: "-0.02em"
headline-md:
fontFamily: "Inter"
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: "Inter"
fontSize: "0.75rem"
fontWeight: 600
lineHeight: 1
letterSpacing: "0.08em"
---

# Quiet High-Contrast Technical Reader

## Overview

### Values

### Anti-Values

## Typography

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

## Layout

### Breakpoints

Mobile <640px uses 20-24px margins and hides side rails; tablet 641-980px keeps a single reading column; desktop >=981px may reveal a subtle table of contents rail.

### Density

Low-to-medium density for prose; code and tables may be dense but must be bounded, padded, and surrounded by rest space.

### Grid

### Responsive

Preserve reading order and measure before preserving side navigation. TOC becomes collapsible on small screens; long code scrolls horizontally within a quiet code surface.

### Whitespace

Vertical whitespace is the primary separator: 56-80px between major sections, 24-36px before subheads, and comfortable paragraph rhythm without visible rules.

## Components

### 0

- **Name**: Near-white reading canvas
- **Rule**: Default pages to #FAFAF7 or #FFFFFF with charcoal #242424 text; reserve gray surfaces for code, notes, and inactive navigation only.

### 1

- **Name**: Bounded prose measure
- **Rule**: Keep long-form paragraphs around 62-72 characters per line with 1.65-1.75 line-height and generous paragraph spacing.

### 2

- **Name**: Typographic hierarchy first
- **Rule**: Use size, weight, line-height, and spacing to establish title, section, subheading, body, code, and meta roles before adding containers.

### 3

### 4

- **Name**: Borderless separation
- **Rule**: Avoid visible card borders and rule-heavy layouts; separate regions with whitespace, alignment, subtle background shifts, and type contrast.

### 5

- **Name**: Readable technical matter
- **Rule**: Code blocks, inline code, tables, and callouts must remain high-contrast, scan-friendly, and visually quieter than the prose hierarchy.

## 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/quiet-technical-reading-surface/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 #FAFAF7 or white as the dominant canvas with charcoal prose and soft gray metadata.
- Do Limit prose width to roughly 62-72 characters and let side rails breathe rather than filling them.
- Do Use the amber highlighter accent only for links, focus rings, active table-of-contents entries, search matches, selections, and marked terms.
- Do Separate sections with spacing, alignment, indentation, and type contrast instead of lines or boxes.
- Do Give code a quiet paper-gray surface, strong monospace contrast, and enough padding to read without turning into a card.
- Do Make captions, breadcrumbs, and metadata visibly secondary while preserving legibility.
- Don't Do not introduce extra accent colors for status, decoration, illustrations, or charts unless required by content semantics.
- Don't Do not wrap every block in bordered cards or rely on horizontal rules for rhythm.
- Don't Do not use pure black body copy on pure white if it creates glare; use charcoal on warm near-white.
- Don't Do not allow paragraphs, tables, or code samples to run full browser width.
- Don't Do not reduce secondary text below readable contrast or size.
- Don't Do not make links look like brand badges; they should feel like highlighted reading marks.

### Accessibility

### Usage Context

Best for documentation, knowledge bases, API references, technical essays, runbooks, research notes, and product education where sustained reading and trust matter more than brand spectacle.

shadcn/ui theme

```json
{
  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
  "name": "quiet-high-contrast-technical-reader",
  "type": "registry:theme",
  "title": "Quiet High-Contrast Technical Reader shadcn Theme",
  "cssVars": {
    "theme": {},
    "light": {
      "background": "#ffffff",
      "foreground": "#111111",
      "card": "#ffffff",
      "card-foreground": "#111111",
      "popover": "#ffffff",
      "popover-foreground": "#111111",
      "primary": "#111111",
      "primary-foreground": "#ffffff",
      "secondary": "#f4f4f5",
      "secondary-foreground": "#111111",
      "muted": "#f4f4f5",
      "muted-foreground": "#111111",
      "accent": "#111111",
      "accent-foreground": "#ffffff",
      "destructive": "#dc2626",
      "border": "#e4e4e7",
      "input": "#e4e4e7",
      "ring": "#111111",
      "chart-1": "#111111",
      "chart-2": "#f4f4f5",
      "chart-3": "#111111",
      "chart-4": "#16a34a",
      "chart-5": "#d97706",
      "sidebar": "#ffffff",
      "sidebar-foreground": "#111111",
      "sidebar-primary": "#111111",
      "sidebar-primary-foreground": "#ffffff",
      "sidebar-accent": "#111111",
      "sidebar-accent-foreground": "#ffffff",
      "sidebar-border": "#e4e4e7",
      "sidebar-ring": "#111111",
      "radius": "0.625rem"
    },
    "dark": {
      "background": "#0f1115",
      "foreground": "#f8fafc",
      "card": "#181b22",
      "card-foreground": "#f8fafc",
      "popover": "#181b22",
      "popover-foreground": "#f8fafc",
      "primary": "#111111",
      "primary-foreground": "#ffffff",
      "secondary": "#252a33",
      "secondary-foreground": "#f8fafc",
      "muted": "#252a33",
      "muted-foreground": "#a1a1aa",
      "accent": "#111111",
      "accent-foreground": "#ffffff",
      "destructive": "#dc2626",
      "border": "#303642",
      "input": "#303642",
      "ring": "#111111",
      "chart-1": "#111111",
      "chart-2": "#f4f4f5",
      "chart-3": "#111111",
      "chart-4": "#16a34a",
      "chart-5": "#d97706",
      "sidebar": "#181b22",
      "sidebar-foreground": "#f8fafc",
      "sidebar-primary": "#111111",
      "sidebar-primary-foreground": "#ffffff",
      "sidebar-accent": "#111111",
      "sidebar-accent-foreground": "#ffffff",
      "sidebar-border": "#303642",
      "sidebar-ring": "#111111",
      "radius": "0.625rem"
    }
  },
  "meta": {
    "source": "katagami",
    "languageId": "quiet-technical-reading-surface",
    "slug": "quiet-high-contrast-technical-reader",
    "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": {
      "color": [
        "accent",
        "accentFocus",
        "accentSoft",
        "canvas",
        "codeSurface",
        "codeText",
        "selection",
        "surface",
        "surfaceSubtle",
        "text",
        "textFaint",
        "textMuted"
      ],
      "radius": [
        "code",
        "none",
        "soft"
      ],
      "shadow": [
        "none"
      ],
      "space": [
        "lg",
        "md",
        "measure",
        "pageX",
        "sm",
        "xl",
        "xs",
        "xxl"
      ],
      "typography": [
        "body",
        "bodySmall",
        "caption",
        "code",
        "display",
        "fontMono",
        "fontSans",
        "fontSerif",
        "section",
        "subheading",
        "title"
      ]
    }
  }
}
```

in the wild

embodiments

Design Language Preview

Quiet High-Contrast Technical Reader

Color Palette

primary

secondary

accent

background

surface

text

muted

border

error

success

warning

info

Typography

Heading One

Heading Two

Heading Three

Heading Four

body

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

caption

Caption text for supplementary information and metadata.

code

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

Buttons

Form Controls

Email address

Message

Navigation

tabs

Overview content area with contextual information about the design language.

segmented control

dropdown menu

Feedback & Status

badges

NewDefaultActivePendingErrorOutline

alerts

Info: A new version is available.

Success: Changes saved successfully.

Warning: Storage is almost full.

Error: Failed to process request.

progress

66% complete

tooltip

avatar

AKJDML

Containers & Overlays

card

Card Title

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

accordion

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

dialog

separator

Data Display

table

Name	Status	Category	Score
Neo Brutalism	Published	Maximalist	94
Aero Glass	Draft	Spatial	87
Signal UI	Review	Enterprise	91

stat cards

Languages

+12%

Elements

3,150

+8%

Usage

18.4k

+23%

DESIGN.md

at a glance

Typography

headline-lgInter · 31px · 700

The quick brown fox jumps

headline-mdInter · 25px · 600

The quick brown fox jumps

body-mdInter · 16px · 400

The quick brown fox jumps

label-mdInter · 12px · 600

The quick brown fox jumps

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

button	ok
card	ok
input	ok

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: #ffffff;
  --foreground: #111111;
  --card: #ffffff;
  --card-foreground: #111111;
  --popover: #ffffff;
  --popover-foreground: #111111;
  --primary: #111111;
  --primary-foreground: #ffffff;
  --secondary: #f4f4f5;
  --secondary-foreground: #111111;
  --muted: #f4f4f5;
  --muted-foreground: #111111;
  --accent: #111111;
  --accent-foreground: #ffffff;
  --destructive: #dc2626;
  --border: #e4e4e7;
  --input: #e4e4e7;
  --ring: #111111;
  --chart-1: #111111;
  --chart-2: #f4f4f5;
  --chart-3: #111111;
  --chart-4: #16a34a;
  --chart-5: #d97706;
  --sidebar: #ffffff;
  --sidebar-foreground: #111111;
  --sidebar-primary: #111111;
  --sidebar-primary-foreground: #ffffff;
  --sidebar-accent: #111111;
  --sidebar-accent-foreground: #ffffff;
  --sidebar-border: #e4e4e7;
  --sidebar-ring: #111111;
  --radius: 0.625rem;
}

.dark {
  --background: #0f1115;
  --foreground: #f8fafc;
  --card: #181b22;
  --card-foreground: #f8fafc;
  --popover: #181b22;
  --popover-foreground: #f8fafc;
  --primary: #111111;
  --primary-foreground: #ffffff;
  --secondary: #252a33;
  --secondary-foreground: #f8fafc;
  --muted: #252a33;
  --muted-foreground: #a1a1aa;
  --accent: #111111;
  --accent-foreground: #ffffff;
  --destructive: #dc2626;
  --border: #303642;
  --input: #303642;
  --ring: #111111;
  --chart-1: #111111;
  --chart-2: #f4f4f5;
  --chart-3: #111111;
  --chart-4: #16a34a;
  --chart-5: #d97706;
  --sidebar: #181b22;
  --sidebar-foreground: #f8fafc;
  --sidebar-primary: #111111;
  --sidebar-primary-foreground: #ffffff;
  --sidebar-accent: #111111;
  --sidebar-accent-foreground: #ffffff;
  --sidebar-border: #303642;
  --sidebar-ring: #111111;
  --radius: 0.625rem;
}

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 QuietHighContrastTechnicalReaderShadcnKit() {
  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">Quiet High-Contrast Technical Reader</h2>
          <p className="mt-1 max-w-xl text-sm text-muted-foreground">
            Use the Katagami registry theme, then compose these shadcn primitives
            with the language-specific component recipes.
          </p>
        </div>
        <Button>Apply theme</Button>
      </div>

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

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

theme JSONcompatibility fallback

{
  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
  "name": "quiet-high-contrast-technical-reader",
  "type": "registry:theme",
  "title": "Quiet High-Contrast Technical Reader shadcn Theme",
  "cssVars": {
    "theme": {},
    "light": {
      "background": "#ffffff",
      "foreground": "#111111",
      "card": "#ffffff",
      "card-foreground": "#111111",
      "popover": "#ffffff",
      "popover-foreground": "#111111",
      "primary": "#111111",
      "primary-foreground": "#ffffff",
      "secondary": "#f4f4f5",
      "secondary-foreground": "#111111",
      "muted": "#f4f4f5",
      "muted-foreground": "#111111",
      "accent": "#111111",
      "accent-foreground": "#ffffff",
      "destructive": "#dc2626",
      "border": "#e4e4e7",
      "input": "#e4e4e7",
      "ring": "#111111",
      "chart-1": "#111111",
      "chart-2": "#f4f4f5",
      "chart-3": "#111111",
      "chart-4": "#16a34a",
      "chart-5": "#d97706",
      "sidebar": "#ffffff",
      "sidebar-foreground": "#111111",
      "sidebar-primary": "#111111",
      "sidebar-primary-foreground": "#ffffff",
      "sidebar-accent": "#111111",
      "sidebar-accent-foreground": "#ffffff",
      "sidebar-border": "#e4e4e7",
      "sidebar-ring": "#111111",
      "radius": "0.625rem"
    },
    "dark": {
      "background": "#0f1115",
      "foreground": "#f8fafc",
      "card": "#181b22",
      "card-foreground": "#f8fafc",
      "popover": "#181b22",
      "popover-foreground": "#f8fafc",
      "primary": "#111111",
      "primary-foreground": "#ffffff",
      "secondary": "#252a33",
      "secondary-foreground": "#f8fafc",
      "muted": "#252a33",
      "muted-foreground": "#a1a1aa",
      "accent": "#111111",
      "accent-foreground": "#ffffff",
      "destructive": "#dc2626",
      "border": "#303642",
      "input": "#303642",
      "ring": "#111111",
      "chart-1": "#111111",
      "chart-2": "#f4f4f5",
      "chart-3": "#111111",
      "chart-4": "#16a34a",
      "chart-5": "#d97706",
      "sidebar": "#181b22",
      "sidebar-foreground": "#f8fafc",
      "sidebar-primary": "#111111",
      "sidebar-primary-foreground": "#ffffff",
      "sidebar-accent": "#111111",
      "sidebar-accent-foreground": "#ffffff",
      "sidebar-border": "#303642",
      "sidebar-ring": "#111111",
      "radius": "0.625rem"
    }
  },
  "meta": {
    "source": "katagami",
    "languageId": "quiet-technical-reading-surface",
    "slug": "quiet-high-contrast-technical-reader",
    "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": {
      "color": [
        "accent",
        "accentFocus",
        "accentSoft",
        "canvas",
        "codeSurface",
        "codeText",
        "selection",
        "surface",
        "surfaceSubtle",
        "text",
        "textFaint",
        "textMuted"
      ],
      "radius": [
        "code",
        "none",
        "soft"
      ],
      "shadow": [
        "none"
      ],
      "space": [
        "lg",
        "md",
        "measure",
        "pageX",
        "sm",
        "xl",
        "xs",
        "xxl"
      ],
      "typography": [
        "body",
        "bodySmall",
        "caption",
        "code",
        "display",
        "fontMono",
        "fontSans",
        "fontSerif",
        "section",
        "subheading",
        "title"
      ]
    }
  }
}

component recipescompatibility fallback

# Quiet High-Contrast Technical Reader shadcn/ui Components

Artifact: `component-recipes-v1`
Author: `katagami-ui-projection`
Language ID: `quiet-technical-reading-surface`
Slug: `quiet-technical-reading-surface`

## Intent

Quiet High-Contrast Technical Reader is a light-mode documentation language where the interface recedes behind carefully measured prose: warm near-white surfaces, charcoal text, typographic hierarchy, generous margins, and one restrained highlighter accent for interaction and emphasis.

## 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:

Defined by the Katagami source fields.

Typography:

{
  "body": "17px/1.72 400 0em",
  "bodySmall": "15px/1.6 400 0em",
  "caption": "13px/1.45 450 0.01em",
  "code": "14px/1.65 450 0em",
  "display": "40px/1.08 650 -0.025em",
  "fontMono": "JetBrains Mono, SFMono-Regular, ui-monospace, Menlo, monospace",
  "fontSans": "Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, Segoe UI, sans-serif",
  "fontSerif": "Charter, Iowan Old Style, Georgia, serif",
  "section": "22px/1.28 620 -0.012em",
  "subheading": "17px/1.45 650 0em",
  "title": "30px/1.18 650 -0.018em"
}

## Visual character to preserve

- Make the source language's structural identity visible in every component state.

## ShadSync visual profile

{
  "family": "system",
  "material": "flat",
  "contour": "default",
  "border": "solid",
  "underlay": false,
  "grain": false,
  "stickerBadges": false,
  "motion": "still",
  "density": "balanced",
  "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/quiet-technical-reading-surface/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 #FAFAF7 or white as the dominant canvas with charcoal prose and soft gray metadata.; Limit prose width to roughly 62-72 characters and let side rails breathe rather than filling them.; Use the amber highlighter accent only for links, focus rings, active table-of-contents entries, search matches, selections, and marked terms.; Separate sections with spacing, alignment, indentation, and type contrast instead of lines or boxes.; Give code a quiet paper-gray surface, strong monospace contrast, and enough padding to read without turning into a card.; Make captions, breadcrumbs, and metadata visibly secondary while preserving legibility.
- Do not: Do not introduce extra accent colors for status, decoration, illustrations, or charts unless required by content semantics.; Do not wrap every block in bordered cards or rely on horizontal rules for rhythm.; Do not use pure black body copy on pure white if it creates glare; use charcoal on warm near-white.; Do not allow paragraphs, tables, or code samples to run full browser width.; Do not reduce secondary text below readable contrast or size.; Do not make links look like brand badges; they should feel like highlighted reading marks.

## 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 QuietHighContrastTechnicalReaderShadcnKit() {
  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">Quiet High-Contrast Technical Reader</h2>
          <p className="mt-1 max-w-xl text-sm text-muted-foreground">
            Use the Katagami registry theme, then compose these shadcn primitives
            with the language-specific component recipes.
          </p>
        </div>
        <Button>Apply theme</Button>
      </div>

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

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

## Layout notes

{
  "breakpoints": "Mobile <640px uses 20-24px margins and hides side rails; tablet 641-980px keeps a single reading column; desktop >=981px may reveal a subtle table of contents rail.",
  "density": "Low-to-medium density for prose; code and tables may be dense but must be bounded, padded, and surrounded by rest space.",
  "grid": "Centered reading column with optional quiet side rail; desktop uses a max content measure near 68ch and page margins from 72px to 112px, while reference pages may use a 12-column shell with prose spanning 6-7 columns.",
  "responsive": "Preserve reading order and measure before preserving side navigation. TOC becomes collapsible on small screens; long code scrolls horizontally within a quiet code surface.",
  "whitespace": "Vertical whitespace is the primary separator: 56-80px between major sections, 24-36px before subheads, and comfortable paragraph rhythm without visible rules."
}

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": "quiet-technical-reading-surface",
    "name": "Quiet High-Contrast Technical Reader",
    "slug": "quiet-technical-reading-surface"
  },
  "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": [],
  "visualProfile": {
    "family": "system",
    "material": "flat",
    "contour": "default",
    "border": "solid",
    "underlay": false,
    "grain": false,
    "stickerBadges": false,
    "motion": "still",
    "density": "balanced",
    "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": "Quiet High-Contrast Technical Reader 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 #FAFAF7 or white as the dominant canvas with charcoal prose and soft gray metadata.",
      "Limit prose width to roughly 62-72 characters and let side rails breathe rather than filling them.",
      "Use the amber highlighter accent only for links, focus rings, active table-of-contents entries, search matches, selections, and marked terms.",
      "Separate sections with spacing, alignment, indentation, and type contrast instead of lines or boxes.",
      "Give code a quiet paper-gray surface, strong monospace contrast, and enough padding to read without turning into a card.",
      "Make captions, breadcrumbs, and metadata visibly secondary while preserving legibility."
    ],
    "dont": [
      "Do not introduce extra accent colors for status, decoration, illustrations, or charts unless required by content semantics.",
      "Do not wrap every block in bordered cards or rely on horizontal rules for rhythm.",
      "Do not use pure black body copy on pure white if it creates glare; use charcoal on warm near-white.",
      "Do not allow paragraphs, tables, or code samples to run full browser width.",
      "Do not reduce secondary text below readable contrast or size.",
      "Do not make links look like brand badges; they should feel like highlighted reading marks."
    ]
  }
}

Quiet High-Contrast Technical Reader

Download DESIGN.md

specification

embodiments

Quiet High-Contrast Technical Reader

Color Palette

Typography

Heading One

Heading Two

Heading Three

Heading Four

Buttons

Form Controls

Navigation

Feedback & Status

Containers & Overlays

Card Title

What are design tokens?

How are embodiments generated?

Can I fork a design language?

Data Display

at a glance

implementation kit

DESIGN.md with shadcn