back to gallerydo avoid
design language·graphite-control-ledger
Graphite Control Ledger
A portable design language for agents: download the markdown first, then inspect the preview, tokens, and rules as needed.
Download DESIGN.md
Portable DESIGN.md source of truth for most agents and apps.
the spec
specification
philosophy
summary
Graphite Control Ledger is a production system language for administrative data, auditability, permissions, and configuration work where the interface should feel like an instrument panel rather than a sales surface. It uses graphite and cool gray layers, a single electric blue command accent, explicit row and focus states, and compact readable typography so dense workflows remain calm, inspectable, and fast. The identity is earned through restraint: no decorative hero language, no gradient spectacle, no inflated headings, only precise surfaces, rules, and state changes that tell operators exactly where they are and what has changed.
values
Readability before personality: labels, captions, metadata, and table values are sized and spaced for repeated scanning, not dramatic first impressions.Operational trust: every interactive element has a visible state for hover, focus, active, selected, disabled, success, warning, and destructive outcomes.Layer honesty: backgrounds, sidebars, tables, panels, popovers, and selected rows are separated by subtle neutral contrast rather than shadows or decorative color.Data dignity: tabular numerals, monospaced identifiers, aligned timestamps, and restrained tracking make audit trails feel precise and verifiable.Brand restraint: electric blue belongs to primary action, focus, and current location only; semantic colors remain separate and never become brand decoration.Dense but humane: compact controls use an 8px spacing basis, generous line-height for rows, and enough whitespace around groups to prevent visual fatigue.Production credibility: the language borrows from control rooms, lab consoles, and enterprise admin shells without imitating terminal nostalgia or sci-fi ornament.
anti-values
×Huge overbold tight-tracked marketing headings that consume space needed for workflow context.×Sterile gradient surfaces, generic grid backgrounds, bento icon boxes, nested rounded stat cards, or pulsing-dot hero pills.×Beige-as-taste neutrality; neutrals are graphite, slate, ink, ceramic, and smoke-blue rather than warm lifestyle paper by default.×Color ambiguity where brand blue, information blue, selection, and status semantics all collapse into the same decorative role.×Browser-default forms, vague hover behavior, invisible keyboard focus, and table rows that do not communicate selection or editability.
tokens
borders4 items
- accent width
- 3px
- character
- Cool gray separators define hierarchy; electric-blue inset borders indicate current location, keyboard focus, and selected records.
- default width
- 1px
- style
- solid
colors22 items
accent
#78A9FF
background
#F4F6F8
border
#D9DEE5
dark_background
#0B0F14
dark_border
#343C46
dark_layer_2
#1F262E
dark_surface
#151A20
error
#DA1E28
graphite
#20262D
info
#0043CE
ink
#0B0F14
layer_0
#F4F6F8
layer_1
#FFFFFF
layer_2
#EEF2F5
layer_3
#E3E8EE
muted
#68717A
primary
#0F62FE
secondary
#3DDC97
success
#198038
surface
#FFFFFF
text
#161A1D
warning
#F1C21B
motion3 items
- duration
- 120ms
- easing
- cubic-bezier(.2,0,.38,.9)
- philosophy
- Short functional transitions only for color, border, and transform on menus; no attention-seeking loops or pulsing indicators.
radii5 items
- full
- 9999px
- lg
- 24px
- md
- 16px
- none
- 0
- sm
- 0
shadows3 items
- lg
- 0 24px 70px rgba(11,15,20,0.22)
- md
- 0 16px 40px rgba(11,15,20,0.14)
- sm
- none
spacing3 items
- base
- 8px
- density
- comfortable row 44px·compact row 36px·control height 32px·touch target 44px
- scale
- 2, 4, 8, 12, 16, 20, 24, 32, 40, 48, 64
surfaces3 items
- bg pattern
- A non-decorative 1px ledger-line rhythm in table and audit areas only, created with borders rather than background grids.
- card style
- Rectangular slabs with radius 16px only for outer panels and radius 0 for table cells, rail items, and stacked controls.
- treatment
- Flat graphite and ceramic layers separated by 1px borders; no gradients; selected surfaces use a blue inset rule plus a faint blue wash.
typography10 items
- base size
- 16px
- body font
- Atkinson Hyperlegible
- google fonts url
- https://fonts.googleapis.com/css2?family=Atkinson+Hyperlegible:wght@400;700&family=Fragment+Mono:ital@0;1&display=swap
- heading font
- Atkinson Hyperlegible
- letter spacing
- -0.02em
- line height
- 1.5
- mono font
- Fragment Mono
- roles
- body Atkinson Hyperlegible 400, 14-16px, line-height 1.5-1.65, measure 58-72 characters for explanatory content.·data Fragment Mono 400 with font-variant-numeric tabular-nums, 12-13px, line-height 1.45 for identifiers, timestamps, counts, and config values.·display Atkinson Hyperlegible 700, 24-30px, line-height 1.15, letter-spacing -0.02em; never oversized and reserved for page context.·fallbacks system-ui, -apple-system, Segoe UI, Roboto, Arial for sans; ui-monospace, SFMono-Regular, Menlo, Consolas, monospace for data.·ui labels Atkinson Hyperlegible 700, 11-12px, line-height 1.25, letter-spacing .04em for short uppercase labels only.
- scale ratio
- 1.16
- ui font
- Atkinson Hyperlegible
rules
composition
Use a three-zone enterprise shell: left command rail, top object/status bar, and a main workbench split between dense table and contextual audit drawer. Align controls to an 8px grid, keep marketing content out of the scene, group filters in compact rows above data, and make the current object visible in both navigation and header. Avoid floating cards inside cards; a panel may contain rows, forms, and tables but not another rounded promotional container.
density
Default density is compact enterprise: 32px controls, 36px table rows, 12-16px internal padding, and 24-32px between major work zones. Increase row height to 44px on touch breakpoints while preserving visible columns through horizontal scroll or stacked key-value records.
hierarchy
Hierarchy comes from layer depth, type weight, row position, and state marks rather than scale. Page titles stay 24-30px, section headings 13-15px, uppercase labels 11-12px with positive tracking, metadata 12px, table values 13px. Primary action is the only filled blue control; secondary actions are bordered or ghost. Warnings and errors appear near the relevant field or row with text and rail cues.
signature patterns
Ledger selection rail: selected navigation items, table records, and audit events all use the same 3px left inset electric-blue rule with a pale blue layer wash.Monospace evidence spine: IDs, times, version numbers, role scopes, and before/after values use Fragment Mono with tabular numerals and consistent fixed-width alignment.Graphite layer ladder: the app shell steps from ink rail to graphite sidebar to ceramic workbench to white table without gradients, using only 1px dividers.State matrix controls: hover, focus, active, selected, disabled, and destructive variants are visible as systematic background, border, outline, and text changes.Audit rail annotations: semantic status is expressed by narrow colored bars, short labels, and textual evidence rather than large colorful cards or decorative badges.
layout
breakpoints
1440px desktop full shell; 1024px tablet collapses secondary rail into a top filter strip; 640px mobile converts tables into stacked record rows and hides nonessential columns behind details.
density
Compact by default for role management, audit review, and configuration panels; density is a product feature because operators compare many rows and permissions at once.
grid
Desktop uses 64px command rail, 248px secondary rail, and fluid workbench up to 1440px with 24px gutters. Panels use 12-column internal grids; forms use two columns until 900px.
responsive
Maintain navigation and current state at every viewport. On mobile, the command rail becomes a bottom bar, the audit drawer moves below the record list, and row actions become inline text buttons.
whitespace
Use 8px increments with tight local spacing and calm macro spacing: 12px between controls, 16px inside panels, 24px between table and drawer, 32px around the workbench edge.
guidance
- Use electric blue sparingly for primary actions, focus outlines, current navigation, and selected record rails.
- Set all numerals in tabular mode and use the mono face for identifiers, timestamps, role codes, IP addresses, and config values.
- Keep table headers sticky, labels short, and column alignment predictable so dense data can be scanned without rereading.
- Pair semantic color with text, rails, or icons; never rely on color alone for status or destructive meaning.
- Use flat neutral layers and precise borders before considering shadow; reserve shadow for true overlays and menus.
- Use 44px targets on touch layouts even when desktop density is compact.
- Write body copy in plain operational language and keep measure under 72 characters for instructions.
- Do not use huge overbold tight-tracked headings, gradient keyword emphasis, generic SaaS hero sections, or decorative bento icon cards.
- Do not make beige the neutral foundation unless the product context explicitly requires paper records or archival warmth.
- Do not merge brand accent and semantic status systems; blue action, info, success, warning, and error must remain distinct.
- Do not nest rounded stat cards inside rounded panels or fill empty space with unrelated metrics.
- Do not hide focus states, reduce table text below 12px, or use low-contrast gray for primary content.
- Do not add pulsing dots, animated grids, glassmorphism, or sterile gradients to create artificial energy.
- Do not use icons without labels for critical admin actions such as permission changes or audit exports.
katagami spec
# Graphite Control Ledger
## Philosophy
Graphite Control Ledger is a production system language for administrative data, auditability, permissions, and configuration work where the interface should feel like an instrument panel rather than a sales surface. It uses graphite and cool gray layers, a single electric blue command accent, explicit row and focus states, and compact readable typography so dense workflows remain calm, inspectable, and fast. The identity is earned through restraint: no decorative hero language, no gradient spectacle, no inflated headings, only precise surfaces, rules, and state changes that tell operators exactly where they are and what has changed.
### Values
- Readability before personality: labels, captions, metadata, and table values are sized and spaced for repeated scanning, not dramatic first impressions.
- Operational trust: every interactive element has a visible state for hover, focus, active, selected, disabled, success, warning, and destructive outcomes.
- Layer honesty: backgrounds, sidebars, tables, panels, popovers, and selected rows are separated by subtle neutral contrast rather than shadows or decorative color.
- Data dignity: tabular numerals, monospaced identifiers, aligned timestamps, and restrained tracking make audit trails feel precise and verifiable.
- Brand restraint: electric blue belongs to primary action, focus, and current location only; semantic colors remain separate and never become brand decoration.
- Dense but humane: compact controls use an 8px spacing basis, generous line-height for rows, and enough whitespace around groups to prevent visual fatigue.
- Production credibility: the language borrows from control rooms, lab consoles, and enterprise admin shells without imitating terminal nostalgia or sci-fi ornament.
### Anti-Values
- Huge overbold tight-tracked marketing headings that consume space needed for workflow context.
- Sterile gradient surfaces, generic grid backgrounds, bento icon boxes, nested rounded stat cards, or pulsing-dot hero pills.
- Beige-as-taste neutrality; neutrals are graphite, slate, ink, ceramic, and smoke-blue rather than warm lifestyle paper by default.
- Color ambiguity where brand blue, information blue, selection, and status semantics all collapse into the same decorative role.
- Browser-default forms, vague hover behavior, invisible keyboard focus, and table rows that do not communicate selection or editability.
### Visual Character
- A fixed-width command rail and a secondary filter rail use darker graphite layers with 1px cool gray separators and squared internal corners.
- Tables use 36px compact rows, sticky header bands, tabular numerals, monospaced IDs, and selected rows marked by a 3px electric-blue inset rule.
- Panels are flat neutral slabs with 1px borders, radius limited to 0, 16px, 24px, and 9999px, and shadows removed except for popover elevation.
- Focus and active states are explicit: 2px electric-blue outlines offset by 2px, active controls darken by one layer, and disabled controls reduce contrast without disappearing.
- Audit changes are shown with narrow status rails and timestamp chips, not colorful cards; semantic colors stay small, textual, and shape-supported.
## Tokens
### Borders
- **Accent Width**: 3px
- **Character**: Cool gray separators define hierarchy; electric-blue inset borders indicate current location, keyboard focus, and selected records.
- **Default Width**: 1px
- **Style**: solid
### Colors
| Name | Value |
|------|-------|
| accent | `#78A9FF` |
| background | `#F4F6F8` |
| border | `#D9DEE5` |
| dark_background | `#0B0F14` |
| dark_border | `#343C46` |
| dark_layer_2 | `#1F262E` |
| dark_surface | `#151A20` |
| error | `#DA1E28` |
| graphite | `#20262D` |
| info | `#0043CE` |
| ink | `#0B0F14` |
| layer_0 | `#F4F6F8` |
| layer_1 | `#FFFFFF` |
| layer_2 | `#EEF2F5` |
| layer_3 | `#E3E8EE` |
| muted | `#68717A` |
| primary | `#0F62FE` |
| secondary | `#3DDC97` |
| success | `#198038` |
| surface | `#FFFFFF` |
| text | `#161A1D` |
| warning | `#F1C21B` |
### Motion
- **Duration**: 120ms
- **Easing**: cubic-bezier(.2,0,.38,.9)
- **Philosophy**: Short functional transitions only for color, border, and transform on menus; no attention-seeking loops or pulsing indicators.
### Radii
- **Full**: 9999px
- **Lg**: 24px
- **Md**: 16px
- **None**: 0
- **Sm**: 0
### Shadows
- **Lg**: 0 24px 70px rgba(11,15,20,0.22)
- **Md**: 0 16px 40px rgba(11,15,20,0.14)
- **Sm**: none
### Spacing
- **Base**: 8px
- **Density**: {"comfortable_row":"44px","compact_row":"36px","control_height":"32px","touch_target":"44px"}
- **Scale**: [2,4,8,12,16,20,24,32,40,48,64]
### Surfaces
- **Bg Pattern**: A non-decorative 1px ledger-line rhythm in table and audit areas only, created with borders rather than background grids.
- **Card Style**: Rectangular slabs with radius 16px only for outer panels and radius 0 for table cells, rail items, and stacked controls.
- **Treatment**: Flat graphite and ceramic layers separated by 1px borders; no gradients; selected surfaces use a blue inset rule plus a faint blue wash.
### Typography
- **Base Size**: 16px
- **Body Font**: Atkinson Hyperlegible
- **Google Fonts Url**: https://fonts.googleapis.com/css2?family=Atkinson+Hyperlegible:wght@400;700&family=Fragment+Mono:ital@0;1&display=swap
- **Heading Font**: Atkinson Hyperlegible
- **Letter Spacing**: -0.02em
- **Line Height**: 1.5
- **Mono Font**: Fragment Mono
- **Roles**: {"body":"Atkinson Hyperlegible 400, 14-16px, line-height 1.5-1.65, measure 58-72 characters for explanatory content.","data":"Fragment Mono 400 with font-variant-numeric tabular-nums, 12-13px, line-height 1.45 for identifiers, timestamps, counts, and config values.","display":"Atkinson Hyperlegible 700, 24-30px, line-height 1.15, letter-spacing -0.02em; never oversized and reserved for page context.","fallbacks":"system-ui, -apple-system, Segoe UI, Roboto, Arial for sans; ui-monospace, SFMono-Regular, Menlo, Consolas, monospace for data.","ui_labels":"Atkinson Hyperlegible 700, 11-12px, line-height 1.25, letter-spacing .04em for short uppercase labels only."}
- **Scale Ratio**: 1.16
- **Ui Font**: Atkinson Hyperlegible
## Rules
### Composition
Use a three-zone enterprise shell: left command rail, top object/status bar, and a main workbench split between dense table and contextual audit drawer. Align controls to an 8px grid, keep marketing content out of the scene, group filters in compact rows above data, and make the current object visible in both navigation and header. Avoid floating cards inside cards; a panel may contain rows, forms, and tables but not another rounded promotional container.
### Density
Default density is compact enterprise: 32px controls, 36px table rows, 12-16px internal padding, and 24-32px between major work zones. Increase row height to 44px on touch breakpoints while preserving visible columns through horizontal scroll or stacked key-value records.
### Hierarchy
Hierarchy comes from layer depth, type weight, row position, and state marks rather than scale. Page titles stay 24-30px, section headings 13-15px, uppercase labels 11-12px with positive tracking, metadata 12px, table values 13px. Primary action is the only filled blue control; secondary actions are bordered or ghost. Warnings and errors appear near the relevant field or row with text and rail cues.
### Signature Patterns
- Ledger selection rail: selected navigation items, table records, and audit events all use the same 3px left inset electric-blue rule with a pale blue layer wash.
- Monospace evidence spine: IDs, times, version numbers, role scopes, and before/after values use Fragment Mono with tabular numerals and consistent fixed-width alignment.
- Graphite layer ladder: the app shell steps from ink rail to graphite sidebar to ceramic workbench to white table without gradients, using only 1px dividers.
- State matrix controls: hover, focus, active, selected, disabled, and destructive variants are visible as systematic background, border, outline, and text changes.
- Audit rail annotations: semantic status is expressed by narrow colored bars, short labels, and textual evidence rather than large colorful cards or decorative badges.
## Layout
### Breakpoints
1440px desktop full shell; 1024px tablet collapses secondary rail into a top filter strip; 640px mobile converts tables into stacked record rows and hides nonessential columns behind details.
### Density
Compact by default for role management, audit review, and configuration panels; density is a product feature because operators compare many rows and permissions at once.
### Grid
Desktop uses 64px command rail, 248px secondary rail, and fluid workbench up to 1440px with 24px gutters. Panels use 12-column internal grids; forms use two columns until 900px.
### Responsive
Maintain navigation and current state at every viewport. On mobile, the command rail becomes a bottom bar, the audit drawer moves below the record list, and row actions become inline text buttons.
### Whitespace
Use 8px increments with tight local spacing and calm macro spacing: 12px between controls, 16px inside panels, 24px between table and drawer, 32px around the workbench edge.
## Guidance
### Do
- Use electric blue sparingly for primary actions, focus outlines, current navigation, and selected record rails.
- Set all numerals in tabular mode and use the mono face for identifiers, timestamps, role codes, IP addresses, and config values.
- Keep table headers sticky, labels short, and column alignment predictable so dense data can be scanned without rereading.
- Pair semantic color with text, rails, or icons; never rely on color alone for status or destructive meaning.
- Use flat neutral layers and precise borders before considering shadow; reserve shadow for true overlays and menus.
- Use 44px targets on touch layouts even when desktop density is compact.
- Write body copy in plain operational language and keep measure under 72 characters for instructions.
### Don't
- Do not use huge overbold tight-tracked headings, gradient keyword emphasis, generic SaaS hero sections, or decorative bento icon cards.
- Do not make beige the neutral foundation unless the product context explicitly requires paper records or archival warmth.
- Do not merge brand accent and semantic status systems; blue action, info, success, warning, and error must remain distinct.
- Do not nest rounded stat cards inside rounded panels or fill empty space with unrelated metrics.
- Do not hide focus states, reduce table text below 12px, or use low-contrast gray for primary content.
- Do not add pulsing dots, animated grids, glassmorphism, or sterile gradients to create artificial energy.
- Do not use icons without labels for critical admin actions such as permission changes or audit exports.
### Accessibility
Maintain WCAG AA contrast for all text and controls, provide 2px focus outlines offset by 2px, preserve visible labels, keep interactive targets at least 32px desktop and 44px touch, and ensure selected/status states include non-color cues.
### Usage Context
Best for IAM consoles, compliance tools, internal admin platforms, audit trail review, configuration management, data governance, billing operations, and enterprise workflow queues.
DESIGN.md
---
version: "alpha"
name: "Graphite Control Ledger"
description: "Agent-curated design language exported from Katagami as DESIGN.md."
colors:
accent: "#78A9FF"
background: "#F4F6F8"
border: "#D9DEE5"
dark_background: "#0B0F14"
dark_border: "#343C46"
dark_layer_2: "#1F262E"
dark_surface: "#151A20"
error: "#DA1E28"
graphite: "#20262D"
info: "#0043CE"
ink: "#0B0F14"
layer_0: "#F4F6F8"
layer_1: "#FFFFFF"
layer_2: "#EEF2F5"
layer_3: "#E3E8EE"
muted: "#68717A"
primary: "#0F62FE"
secondary: "#3DDC97"
success: "#198038"
surface: "#FFFFFF"
text: "#161A1D"
warning: "#F1C21B"
typography:
headline-lg:
fontFamily: "Atkinson Hyperlegible"
fontSize: "1.561rem"
fontWeight: 700
lineHeight: 1.1
letterSpacing: "-0.02em"
headline-md:
fontFamily: "Atkinson Hyperlegible"
fontSize: "1.346rem"
fontWeight: 600
lineHeight: 1.15
letterSpacing: "-0.02em"
body-md:
fontFamily: "Atkinson Hyperlegible"
fontSize: "16px"
fontWeight: 400
lineHeight: 1.5
letterSpacing: "-0.02em"
label-md:
fontFamily: "Fragment Mono"
fontSize: "0.75rem"
fontWeight: 600
lineHeight: 1
letterSpacing: "0.08em"
rounded:
full: "9999px"
lg: "24px"
md: "16px"
none: "0px"
sm: "0px"
spacing:
base: "8px"
xs: "2px"
sm: "4px"
md: "8px"
lg: "12px"
xl: "16px"
2xl: "20px"
3xl: "24px"
4xl: "32px"
step-8: "40px"
step-9: "48px"
step-10: "64px"
components:
color-reference-accent:
backgroundColor: "{colors.accent}"
color-reference-background:
backgroundColor: "{colors.background}"
color-reference-border:
backgroundColor: "{colors.border}"
color-reference-dark_background:
backgroundColor: "{colors.dark_background}"
color-reference-dark_border:
backgroundColor: "{colors.dark_border}"
color-reference-dark_layer_2:
backgroundColor: "{colors.dark_layer_2}"
color-reference-dark_surface:
backgroundColor: "{colors.dark_surface}"
color-reference-error:
backgroundColor: "{colors.error}"
color-reference-graphite:
backgroundColor: "{colors.graphite}"
color-reference-info:
backgroundColor: "{colors.info}"
color-reference-ink:
backgroundColor: "{colors.ink}"
color-reference-layer_0:
backgroundColor: "{colors.layer_0}"
color-reference-layer_1:
backgroundColor: "{colors.layer_1}"
color-reference-layer_2:
backgroundColor: "{colors.layer_2}"
color-reference-layer_3:
backgroundColor: "{colors.layer_3}"
color-reference-muted:
backgroundColor: "{colors.muted}"
color-reference-primary:
backgroundColor: "{colors.primary}"
color-reference-secondary:
backgroundColor: "{colors.secondary}"
color-reference-success:
backgroundColor: "{colors.success}"
color-reference-surface:
backgroundColor: "{colors.surface}"
color-reference-text:
backgroundColor: "{colors.text}"
color-reference-warning:
backgroundColor: "{colors.warning}"
button-primary:
backgroundColor: "{colors.primary}"
textColor: "#ffffff"
typography: "{typography.label-md}"
rounded: "{rounded.md}"
padding: "{spacing.md}"
card-surface:
backgroundColor: "{colors.surface}"
textColor: "{colors.text}"
rounded: "{rounded.md}"
padding: "{spacing.md}"
input-default:
backgroundColor: "{colors.surface}"
textColor: "{colors.text}"
rounded: "{rounded.md}"
height: "44px"
---
# Graphite Control Ledger
## Overview
Graphite Control Ledger is a production system language for administrative data, auditability, permissions, and configuration work where the interface should feel like an instrument panel rather than a sales surface. It uses graphite and cool gray layers, a single electric blue command accent, explicit row and focus states, and compact readable typography so dense workflows remain calm, inspectable, and fast. The identity is earned through restraint: no decorative hero language, no gradient spectacle, no inflated headings, only precise surfaces, rules, and state changes that tell operators exactly where they are and what has changed.
### Values
- Readability before personality: labels, captions, metadata, and table values are sized and spaced for repeated scanning, not dramatic first impressions.
- Operational trust: every interactive element has a visible state for hover, focus, active, selected, disabled, success, warning, and destructive outcomes.
- Layer honesty: backgrounds, sidebars, tables, panels, popovers, and selected rows are separated by subtle neutral contrast rather than shadows or decorative color.
- Data dignity: tabular numerals, monospaced identifiers, aligned timestamps, and restrained tracking make audit trails feel precise and verifiable.
- Brand restraint: electric blue belongs to primary action, focus, and current location only; semantic colors remain separate and never become brand decoration.
- Dense but humane: compact controls use an 8px spacing basis, generous line-height for rows, and enough whitespace around groups to prevent visual fatigue.
- Production credibility: the language borrows from control rooms, lab consoles, and enterprise admin shells without imitating terminal nostalgia or sci-fi ornament.
### Anti-Values
- Huge overbold tight-tracked marketing headings that consume space needed for workflow context.
- Sterile gradient surfaces, generic grid backgrounds, bento icon boxes, nested rounded stat cards, or pulsing-dot hero pills.
- Beige-as-taste neutrality; neutrals are graphite, slate, ink, ceramic, and smoke-blue rather than warm lifestyle paper by default.
- Color ambiguity where brand blue, information blue, selection, and status semantics all collapse into the same decorative role.
- Browser-default forms, vague hover behavior, invisible keyboard focus, and table rows that do not communicate selection or editability.
### Visual Character
- A fixed-width command rail and a secondary filter rail use darker graphite layers with 1px cool gray separators and squared internal corners.
- Tables use 36px compact rows, sticky header bands, tabular numerals, monospaced IDs, and selected rows marked by a 3px electric-blue inset rule.
- Panels are flat neutral slabs with 1px borders, radius limited to 0, 16px, 24px, and 9999px, and shadows removed except for popover elevation.
- Focus and active states are explicit: 2px electric-blue outlines offset by 2px, active controls darken by one layer, and disabled controls reduce contrast without disappearing.
- Audit changes are shown with narrow status rails and timestamp chips, not colorful cards; semantic colors stay small, textual, and shape-supported.
## Colors
Use the YAML color tokens as the normative palette. The prose below names the roles agents should preserve when generating UI.
| Token | Value |
|-------|-------|
| accent | `#78A9FF` |
| background | `#F4F6F8` |
| border | `#D9DEE5` |
| dark_background | `#0B0F14` |
| dark_border | `#343C46` |
| dark_layer_2 | `#1F262E` |
| dark_surface | `#151A20` |
| error | `#DA1E28` |
| graphite | `#20262D` |
| info | `#0043CE` |
| ink | `#0B0F14` |
| layer_0 | `#F4F6F8` |
| layer_1 | `#FFFFFF` |
| layer_2 | `#EEF2F5` |
| layer_3 | `#E3E8EE` |
| muted | `#68717A` |
| primary | `#0F62FE` |
| secondary | `#3DDC97` |
| success | `#198038` |
| surface | `#FFFFFF` |
| text | `#161A1D` |
| warning | `#F1C21B` |
## Typography
- **Headline-Lg**: Atkinson Hyperlegible, 1.561rem, weight 700, line-height 1.1.
- **Headline-Md**: Atkinson Hyperlegible, 1.346rem, weight 600, line-height 1.15.
- **Body-Md**: Atkinson Hyperlegible, 16px, weight 400, line-height 1.5.
- **Label-Md**: Fragment Mono, 0.75rem, weight 600, line-height 1.
## Layout
### Spacing Tokens
- **Base**: `8px`
- **Xs**: `2px`
- **Sm**: `4px`
- **Md**: `8px`
- **Lg**: `12px`
- **Xl**: `16px`
- **2xl**: `20px`
- **3xl**: `24px`
- **4xl**: `32px`
- **Step-8**: `40px`
- **Step-9**: `48px`
- **Step-10**: `64px`
### Breakpoints
1440px desktop full shell; 1024px tablet collapses secondary rail into a top filter strip; 640px mobile converts tables into stacked record rows and hides nonessential columns behind details.
### Density
Compact by default for role management, audit review, and configuration panels; density is a product feature because operators compare many rows and permissions at once.
### Grid
Desktop uses 64px command rail, 248px secondary rail, and fluid workbench up to 1440px with 24px gutters. Panels use 12-column internal grids; forms use two columns until 900px.
### Responsive
Maintain navigation and current state at every viewport. On mobile, the command rail becomes a bottom bar, the audit drawer moves below the record list, and row actions become inline text buttons.
### Whitespace
Use 8px increments with tight local spacing and calm macro spacing: 12px between controls, 16px inside panels, 24px between table and drawer, 32px around the workbench edge.
## Elevation & Depth
### Shadows
- **Lg**: 0 24px 70px rgba(11,15,20,0.22)
- **Md**: 0 16px 40px rgba(11,15,20,0.14)
- **Sm**: none
## Shapes
### Rounded
- **Full**: `9999px`
- **Lg**: `24px`
- **Md**: `16px`
- **None**: `0px`
- **Sm**: `0px`
### Surfaces
- **Bg Pattern**: A non-decorative 1px ledger-line rhythm in table and audit areas only, created with borders rather than background grids.
- **Card Style**: Rectangular slabs with radius 16px only for outer panels and radius 0 for table cells, rail items, and stacked controls.
- **Treatment**: Flat graphite and ceramic layers separated by 1px borders; no gradients; selected surfaces use a blue inset rule plus a faint blue wash.
### Borders
- **Accent Width**: 3px
- **Character**: Cool gray separators define hierarchy; electric-blue inset borders indicate current location, keyboard focus, and selected records.
- **Default Width**: 1px
- **Style**: solid
## Components
### Composition
Use a three-zone enterprise shell: left command rail, top object/status bar, and a main workbench split between dense table and contextual audit drawer. Align controls to an 8px grid, keep marketing content out of the scene, group filters in compact rows above data, and make the current object visible in both navigation and header. Avoid floating cards inside cards; a panel may contain rows, forms, and tables but not another rounded promotional container.
### Density
Default density is compact enterprise: 32px controls, 36px table rows, 12-16px internal padding, and 24-32px between major work zones. Increase row height to 44px on touch breakpoints while preserving visible columns through horizontal scroll or stacked key-value records.
### Hierarchy
Hierarchy comes from layer depth, type weight, row position, and state marks rather than scale. Page titles stay 24-30px, section headings 13-15px, uppercase labels 11-12px with positive tracking, metadata 12px, table values 13px. Primary action is the only filled blue control; secondary actions are bordered or ghost. Warnings and errors appear near the relevant field or row with text and rail cues.
### Signature Patterns
- Ledger selection rail: selected navigation items, table records, and audit events all use the same 3px left inset electric-blue rule with a pale blue layer wash.
- Monospace evidence spine: IDs, times, version numbers, role scopes, and before/after values use Fragment Mono with tabular numerals and consistent fixed-width alignment.
- Graphite layer ladder: the app shell steps from ink rail to graphite sidebar to ceramic workbench to white table without gradients, using only 1px dividers.
- State matrix controls: hover, focus, active, selected, disabled, and destructive variants are visible as systematic background, border, outline, and text changes.
- Audit rail annotations: semantic status is expressed by narrow colored bars, short labels, and textual evidence rather than large colorful cards or decorative badges.
## 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/graphite-control-ledger/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 electric blue sparingly for primary actions, focus outlines, current navigation, and selected record rails.
- Do Set all numerals in tabular mode and use the mono face for identifiers, timestamps, role codes, IP addresses, and config values.
- Do Keep table headers sticky, labels short, and column alignment predictable so dense data can be scanned without rereading.
- Do Pair semantic color with text, rails, or icons; never rely on color alone for status or destructive meaning.
- Do Use flat neutral layers and precise borders before considering shadow; reserve shadow for true overlays and menus.
- Do Use 44px targets on touch layouts even when desktop density is compact.
- Do Write body copy in plain operational language and keep measure under 72 characters for instructions.
- Don't Do not use huge overbold tight-tracked headings, gradient keyword emphasis, generic SaaS hero sections, or decorative bento icon cards.
- Don't Do not make beige the neutral foundation unless the product context explicitly requires paper records or archival warmth.
- Don't Do not merge brand accent and semantic status systems; blue action, info, success, warning, and error must remain distinct.
- Don't Do not nest rounded stat cards inside rounded panels or fill empty space with unrelated metrics.
- Don't Do not hide focus states, reduce table text below 12px, or use low-contrast gray for primary content.
- Don't Do not add pulsing dots, animated grids, glassmorphism, or sterile gradients to create artificial energy.
- Don't Do not use icons without labels for critical admin actions such as permission changes or audit exports.
### Accessibility
Maintain WCAG AA contrast for all text and controls, provide 2px focus outlines offset by 2px, preserve visible labels, keep interactive targets at least 32px desktop and 44px touch, and ensure selected/status states include non-color cues.
### Usage Context
Best for IAM consoles, compliance tools, internal admin platforms, audit trail review, configuration management, data governance, billing operations, and enterprise workflow queues.
shadcn/ui theme
```json
{
"$schema": "https://ui.shadcn.com/schema/registry-item.json",
"name": "graphite-control-ledger",
"type": "registry:theme",
"title": "Graphite Control Ledger shadcn Theme",
"cssVars": {
"theme": {},
"light": {
"background": "#F4F6F8",
"foreground": "#161A1D",
"card": "#FFFFFF",
"card-foreground": "#161A1D",
"popover": "#FFFFFF",
"popover-foreground": "#161A1D",
"primary": "#0F62FE",
"primary-foreground": "#ffffff",
"secondary": "#3DDC97",
"secondary-foreground": "#111111",
"muted": "#68717A",
"muted-foreground": "#161A1D",
"accent": "#78A9FF",
"accent-foreground": "#ffffff",
"destructive": "#DA1E28",
"border": "#D9DEE5",
"input": "#D9DEE5",
"ring": "#78A9FF",
"chart-1": "#0F62FE",
"chart-2": "#3DDC97",
"chart-3": "#78A9FF",
"chart-4": "#198038",
"chart-5": "#F1C21B",
"sidebar": "#FFFFFF",
"sidebar-foreground": "#161A1D",
"sidebar-primary": "#0F62FE",
"sidebar-primary-foreground": "#ffffff",
"sidebar-accent": "#0043CE",
"sidebar-accent-foreground": "#ffffff",
"sidebar-border": "#D9DEE5",
"sidebar-ring": "#78A9FF",
"radius": "16px"
},
"dark": {
"background": "#0f1115",
"foreground": "#f8fafc",
"card": "#181b22",
"card-foreground": "#f8fafc",
"popover": "#181b22",
"popover-foreground": "#f8fafc",
"primary": "#0F62FE",
"primary-foreground": "#ffffff",
"secondary": "#252a33",
"secondary-foreground": "#f8fafc",
"muted": "#252a33",
"muted-foreground": "#a1a1aa",
"accent": "#78A9FF",
"accent-foreground": "#ffffff",
"destructive": "#DA1E28",
"border": "#303642",
"input": "#303642",
"ring": "#78A9FF",
"chart-1": "#0F62FE",
"chart-2": "#3DDC97",
"chart-3": "#78A9FF",
"chart-4": "#198038",
"chart-5": "#F1C21B",
"sidebar": "#181b22",
"sidebar-foreground": "#f8fafc",
"sidebar-primary": "#0F62FE",
"sidebar-primary-foreground": "#ffffff",
"sidebar-accent": "#78A9FF",
"sidebar-accent-foreground": "#ffffff",
"sidebar-border": "#303642",
"sidebar-ring": "#78A9FF",
"radius": "16px"
}
},
"meta": {
"source": "katagami",
"languageId": "graphite-control-ledger",
"slug": "graphite-control-ledger",
"componentManifest": [
"button",
"card",
"input",
"textarea",
"select",
"dialog",
"sheet",
"tabs",
"badge",
"separator",
"checkbox",
"switch",
"slider",
"tooltip",
"dropdown-menu",
"table"
],
"installCommand": "npx shadcn@latest add button card input textarea select dialog sheet tabs badge separator checkbox switch slider tooltip dropdown-menu table",
"nativeTokenNames": {
"borders": [
"accent_width",
"character",
"default_width",
"style"
],
"colors": [
"accent",
"background",
"border",
"dark_background",
"dark_border",
"dark_layer_2",
"dark_surface",
"error",
"graphite",
"info",
"ink",
"layer_0",
"layer_1",
"layer_2",
"layer_3",
"muted",
"primary",
"secondary",
"success",
"surface",
"text",
"warning"
],
"motion": [
"duration",
"easing",
"philosophy"
],
"radii": [
"full",
"lg",
"md",
"none",
"sm"
],
"shadows": [
"lg",
"md",
"sm"
],
"spacing": [
"base",
"density",
"scale"
],
"surfaces": [
"bg_pattern",
"card_style",
"treatment"
],
"typography": [
"base_size",
"body_font",
"google_fonts_url",
"heading_font",
"letter_spacing",
"line_height",
"mono_font",
"roles",
"scale_ratio",
"ui_font"
]
}
}
}
```in the wild
embodiments
the full element showcase
embodiment · graphite-control-ledger
DESIGN.md
at a glance
Typography
headline-lgAtkinson Hyperlegible · 25px · 700
The quick brown fox jumps
headline-mdAtkinson Hyperlegible · 22px · 600
The quick brown fox jumps
body-mdAtkinson Hyperlegible · 16px · 400
The quick brown fox jumps
label-mdFragment Mono · 12px · 600
The quick brown fox jumps
Components
New
Card title
Components rendered with this language’s tokens — colors, type, and rounded corners as specified.
Spacing
- base8px
- xs2px
- sm4px
- md8px
- lg12px
- xl16px
- 2xl20px
- 3xl24px
- 4xl32px
- step-840px
- step-948px
- step-1064px
Shape
full9999px
lg24px
md16px
none0px
sm0px
shadcn/ui
implementation kit
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 tabletheme css
:root {
--background: #F4F6F8;
--foreground: #161A1D;
--card: #FFFFFF;
--card-foreground: #161A1D;
--popover: #FFFFFF;
--popover-foreground: #161A1D;
--primary: #0F62FE;
--primary-foreground: #ffffff;
--secondary: #3DDC97;
--secondary-foreground: #111111;
--muted: #68717A;
--muted-foreground: #161A1D;
--accent: #78A9FF;
--accent-foreground: #ffffff;
--destructive: #DA1E28;
--border: #D9DEE5;
--input: #D9DEE5;
--ring: #78A9FF;
--chart-1: #0F62FE;
--chart-2: #3DDC97;
--chart-3: #78A9FF;
--chart-4: #198038;
--chart-5: #F1C21B;
--sidebar: #FFFFFF;
--sidebar-foreground: #161A1D;
--sidebar-primary: #0F62FE;
--sidebar-primary-foreground: #ffffff;
--sidebar-accent: #0043CE;
--sidebar-accent-foreground: #ffffff;
--sidebar-border: #D9DEE5;
--sidebar-ring: #78A9FF;
--radius: 16px;
}
.dark {
--background: #0f1115;
--foreground: #f8fafc;
--card: #181b22;
--card-foreground: #f8fafc;
--popover: #181b22;
--popover-foreground: #f8fafc;
--primary: #0F62FE;
--primary-foreground: #ffffff;
--secondary: #252a33;
--secondary-foreground: #f8fafc;
--muted: #252a33;
--muted-foreground: #a1a1aa;
--accent: #78A9FF;
--accent-foreground: #ffffff;
--destructive: #DA1E28;
--border: #303642;
--input: #303642;
--ring: #78A9FF;
--chart-1: #0F62FE;
--chart-2: #3DDC97;
--chart-3: #78A9FF;
--chart-4: #198038;
--chart-5: #F1C21B;
--sidebar: #181b22;
--sidebar-foreground: #f8fafc;
--sidebar-primary: #0F62FE;
--sidebar-primary-foreground: #ffffff;
--sidebar-accent: #78A9FF;
--sidebar-accent-foreground: #ffffff;
--sidebar-border: #303642;
--sidebar-ring: #78A9FF;
--radius: 16px;
}
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 GraphiteControlLedgerShadcnKit() {
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">Graphite Control Ledger</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": "graphite-control-ledger",
"type": "registry:theme",
"title": "Graphite Control Ledger shadcn Theme",
"cssVars": {
"theme": {},
"light": {
"background": "#F4F6F8",
"foreground": "#161A1D",
"card": "#FFFFFF",
"card-foreground": "#161A1D",
"popover": "#FFFFFF",
"popover-foreground": "#161A1D",
"primary": "#0F62FE",
"primary-foreground": "#ffffff",
"secondary": "#3DDC97",
"secondary-foreground": "#111111",
"muted": "#68717A",
"muted-foreground": "#161A1D",
"accent": "#78A9FF",
"accent-foreground": "#ffffff",
"destructive": "#DA1E28",
"border": "#D9DEE5",
"input": "#D9DEE5",
"ring": "#78A9FF",
"chart-1": "#0F62FE",
"chart-2": "#3DDC97",
"chart-3": "#78A9FF",
"chart-4": "#198038",
"chart-5": "#F1C21B",
"sidebar": "#FFFFFF",
"sidebar-foreground": "#161A1D",
"sidebar-primary": "#0F62FE",
"sidebar-primary-foreground": "#ffffff",
"sidebar-accent": "#0043CE",
"sidebar-accent-foreground": "#ffffff",
"sidebar-border": "#D9DEE5",
"sidebar-ring": "#78A9FF",
"radius": "16px"
},
"dark": {
"background": "#0f1115",
"foreground": "#f8fafc",
"card": "#181b22",
"card-foreground": "#f8fafc",
"popover": "#181b22",
"popover-foreground": "#f8fafc",
"primary": "#0F62FE",
"primary-foreground": "#ffffff",
"secondary": "#252a33",
"secondary-foreground": "#f8fafc",
"muted": "#252a33",
"muted-foreground": "#a1a1aa",
"accent": "#78A9FF",
"accent-foreground": "#ffffff",
"destructive": "#DA1E28",
"border": "#303642",
"input": "#303642",
"ring": "#78A9FF",
"chart-1": "#0F62FE",
"chart-2": "#3DDC97",
"chart-3": "#78A9FF",
"chart-4": "#198038",
"chart-5": "#F1C21B",
"sidebar": "#181b22",
"sidebar-foreground": "#f8fafc",
"sidebar-primary": "#0F62FE",
"sidebar-primary-foreground": "#ffffff",
"sidebar-accent": "#78A9FF",
"sidebar-accent-foreground": "#ffffff",
"sidebar-border": "#303642",
"sidebar-ring": "#78A9FF",
"radius": "16px"
}
},
"meta": {
"source": "katagami",
"languageId": "graphite-control-ledger",
"slug": "graphite-control-ledger",
"componentManifest": [
"button",
"card",
"input",
"textarea",
"select",
"dialog",
"sheet",
"tabs",
"badge",
"separator",
"checkbox",
"switch",
"slider",
"tooltip",
"dropdown-menu",
"table"
],
"installCommand": "npx shadcn@latest add button card input textarea select dialog sheet tabs badge separator checkbox switch slider tooltip dropdown-menu table",
"nativeTokenNames": {
"borders": [
"accent_width",
"character",
"default_width",
"style"
],
"colors": [
"accent",
"background",
"border",
"dark_background",
"dark_border",
"dark_layer_2",
"dark_surface",
"error",
"graphite",
"info",
"ink",
"layer_0",
"layer_1",
"layer_2",
"layer_3",
"muted",
"primary",
"secondary",
"success",
"surface",
"text",
"warning"
],
"motion": [
"duration",
"easing",
"philosophy"
],
"radii": [
"full",
"lg",
"md",
"none",
"sm"
],
"shadows": [
"lg",
"md",
"sm"
],
"spacing": [
"base",
"density",
"scale"
],
"surfaces": [
"bg_pattern",
"card_style",
"treatment"
],
"typography": [
"base_size",
"body_font",
"google_fonts_url",
"heading_font",
"letter_spacing",
"line_height",
"mono_font",
"roles",
"scale_ratio",
"ui_font"
]
}
}
}
component recipescompatibility fallback
# Graphite Control Ledger shadcn/ui Components
Artifact: `component-recipes-v1`
Author: `katagami-ui-projection`
Language ID: `graphite-control-ledger`
Slug: `graphite-control-ledger`
## Intent
Graphite Control Ledger is a production system language for administrative data, auditability, permissions, and configuration work where the interface should feel like an instrument panel rather than a sales surface. It uses graphite and cool gray layers, a single electric blue command accent, explicit row and focus states, and compact readable typography so dense workflows remain calm, inspectable, and fast. The identity is earned through restraint: no decorative hero language, no gradient spectacle, no inflated headings, only precise surfaces, rules, and state changes that tell operators exactly where they are and what has changed.
## Required primitives
- button
- card
- input
- textarea
- select
- dialog
- sheet
- tabs
- badge
- separator
- checkbox
- switch
- slider
- tooltip
- dropdown-menu
- table
Install with `npx shadcn@latest add button card input textarea select dialog sheet tabs badge separator checkbox switch slider tooltip dropdown-menu table`.
## Token cues
Colors:
{
"accent": "#78A9FF",
"background": "#F4F6F8",
"border": "#D9DEE5",
"dark_background": "#0B0F14",
"dark_border": "#343C46",
"dark_layer_2": "#1F262E",
"dark_surface": "#151A20",
"error": "#DA1E28",
"graphite": "#20262D",
"info": "#0043CE",
"ink": "#0B0F14",
"layer_0": "#F4F6F8",
"layer_1": "#FFFFFF",
"layer_2": "#EEF2F5",
"layer_3": "#E3E8EE",
"muted": "#68717A",
"primary": "#0F62FE",
"secondary": "#3DDC97",
"success": "#198038",
"surface": "#FFFFFF",
"text": "#161A1D",
"warning": "#F1C21B"
}
Typography:
{
"base_size": "16px",
"body_font": "Atkinson Hyperlegible",
"google_fonts_url": "https://fonts.googleapis.com/css2?family=Atkinson+Hyperlegible:wght@400;700&family=Fragment+Mono:ital@0;1&display=swap",
"heading_font": "Atkinson Hyperlegible",
"letter_spacing": "-0.02em",
"line_height": 1.5,
"mono_font": "Fragment Mono",
"roles": {
"body": "Atkinson Hyperlegible 400, 14-16px, line-height 1.5-1.65, measure 58-72 characters for explanatory content.",
"data": "Fragment Mono 400 with font-variant-numeric tabular-nums, 12-13px, line-height 1.45 for identifiers, timestamps, counts, and config values.",
"display": "Atkinson Hyperlegible 700, 24-30px, line-height 1.15, letter-spacing -0.02em; never oversized and reserved for page context.",
"fallbacks": "system-ui, -apple-system, Segoe UI, Roboto, Arial for sans; ui-monospace, SFMono-Regular, Menlo, Consolas, monospace for data.",
"ui_labels": "Atkinson Hyperlegible 700, 11-12px, line-height 1.25, letter-spacing .04em for short uppercase labels only."
},
"scale_ratio": 1.16,
"ui_font": "Atkinson Hyperlegible"
}
## Visual character to preserve
- A fixed-width command rail and a secondary filter rail use darker graphite layers with 1px cool gray separators and squared internal corners.
- Tables use 36px compact rows, sticky header bands, tabular numerals, monospaced IDs, and selected rows marked by a 3px electric-blue inset rule.
- Panels are flat neutral slabs with 1px borders, radius limited to 0, 16px, 24px, and 9999px, and shadows removed except for popover elevation.
- Focus and active states are explicit: 2px electric-blue outlines offset by 2px, active controls darken by one layer, and disabled controls reduce contrast without disappearing.
- Audit changes are shown with narrow status rails and timestamp chips, not colorful cards; semantic colors stay small, textual, and shape-supported.
## ShadSync visual profile
{
"family": "system",
"material": "flat",
"contour": "default",
"border": "solid",
"underlay": true,
"grain": false,
"stickerBadges": true,
"motion": "still",
"density": "dense",
"accents": [
"primary",
"accent",
"secondary",
"muted"
]
}
## Signature component recipes
### Button
Use `Button` for primary, secondary, outline, and ghost actions. Primary actions must expose the language's strongest contrast pair, while secondary and ghost actions should preserve the surface treatment instead of falling back to default neutral SaaS styling.
### Card
Use `Card`, `CardHeader`, `CardContent`, `CardFooter`, and `CardAction` as the main composition frame. Cards should demonstrate the language's surface, border, hierarchy, and density rules rather than appearing as generic rounded rectangles.
### Input and Textarea
Use `Input` and `Textarea` with visible focus rings, field labels, validation states, and the language's rhythm. Forms should show real product content, not placeholder-only controls.
### Select, Tabs, and Table
Use `Select`, `Tabs`, and `Table` to prove navigation, filtering, and dense data states. The table should show row rhythm, separators, hover/focus states, and an empty or status state when the language calls for it.
### Dialog and Sheet
Use `Dialog` for centered decisions and `Sheet` for contextual editing. Both should inherit the language's spacing, border, overlay, and motion rules.
## Preview shots
- `application-shell`: dashboard or workspace shell with navigation, cards, forms, and state badges.
- `detail-editor`: focused editing flow using input, textarea, select, switch/checkbox, dialog or sheet, and action buttons.
- `data-operations`: table-heavy operational view with tabs, dropdown menu affordances, badges, and destructive/empty states.
- Each preview shot must include a renderable `scene` payload with concrete headline, description, actions, and rows/fields/stats for the UI preview.
## Implementation contract
- Start from local `ui/src/components/ui` shadcn-style primitives; do not create a second component system.
- Apply `/katagami/shadcn/graphite-control-ledger/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 electric blue sparingly for primary actions, focus outlines, current navigation, and selected record rails.; Set all numerals in tabular mode and use the mono face for identifiers, timestamps, role codes, IP addresses, and config values.; Keep table headers sticky, labels short, and column alignment predictable so dense data can be scanned without rereading.; Pair semantic color with text, rails, or icons; never rely on color alone for status or destructive meaning.; Use flat neutral layers and precise borders before considering shadow; reserve shadow for true overlays and menus.; Use 44px targets on touch layouts even when desktop density is compact.; Write body copy in plain operational language and keep measure under 72 characters for instructions.
- Do not: Do not use huge overbold tight-tracked headings, gradient keyword emphasis, generic SaaS hero sections, or decorative bento icon cards.; Do not make beige the neutral foundation unless the product context explicitly requires paper records or archival warmth.; Do not merge brand accent and semantic status systems; blue action, info, success, warning, and error must remain distinct.; Do not nest rounded stat cards inside rounded panels or fill empty space with unrelated metrics.; Do not hide focus states, reduce table text below 12px, or use low-contrast gray for primary content.; Do not add pulsing dots, animated grids, glassmorphism, or sterile gradients to create artificial energy.; Do not use icons without labels for critical admin actions such as permission changes or audit exports.
## 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 GraphiteControlLedgerShadcnKit() {
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">Graphite Control Ledger</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": "1440px desktop full shell; 1024px tablet collapses secondary rail into a top filter strip; 640px mobile converts tables into stacked record rows and hides nonessential columns behind details.",
"density": "Compact by default for role management, audit review, and configuration panels; density is a product feature because operators compare many rows and permissions at once.",
"grid": "Desktop uses 64px command rail, 248px secondary rail, and fluid workbench up to 1440px with 24px gutters. Panels use 12-column internal grids; forms use two columns until 900px.",
"responsive": "Maintain navigation and current state at every viewport. On mobile, the command rail becomes a bottom bar, the audit drawer moves below the record list, and row actions become inline text buttons.",
"whitespace": "Use 8px increments with tight local spacing and calm macro spacing: 12px between controls, 16px inside panels, 24px between table and drawer, 32px around the workbench edge."
}
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": "graphite-control-ledger",
"name": "Graphite Control Ledger",
"slug": "graphite-control-ledger"
},
"installCommand": "npx shadcn@latest add button card input textarea select dialog sheet tabs badge separator checkbox switch slider tooltip dropdown-menu table",
"primitives": [
"button",
"card",
"input",
"textarea",
"select",
"dialog",
"sheet",
"tabs",
"badge",
"separator",
"checkbox",
"switch",
"slider",
"tooltip",
"dropdown-menu",
"table"
],
"identityNotes": [
"A fixed-width command rail and a secondary filter rail use darker graphite layers with 1px cool gray separators and squared internal corners.",
"Tables use 36px compact rows, sticky header bands, tabular numerals, monospaced IDs, and selected rows marked by a 3px electric-blue inset rule.",
"Panels are flat neutral slabs with 1px borders, radius limited to 0, 16px, 24px, and 9999px, and shadows removed except for popover elevation.",
"Focus and active states are explicit: 2px electric-blue outlines offset by 2px, active controls darken by one layer, and disabled controls reduce contrast without disappearing.",
"Audit changes are shown with narrow status rails and timestamp chips, not colorful cards; semantic colors stay small, textual, and shape-supported."
],
"visualProfile": {
"family": "system",
"material": "flat",
"contour": "default",
"border": "solid",
"underlay": true,
"grain": false,
"stickerBadges": true,
"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": "Graphite Control Ledger 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 electric blue sparingly for primary actions, focus outlines, current navigation, and selected record rails.",
"Set all numerals in tabular mode and use the mono face for identifiers, timestamps, role codes, IP addresses, and config values.",
"Keep table headers sticky, labels short, and column alignment predictable so dense data can be scanned without rereading.",
"Pair semantic color with text, rails, or icons; never rely on color alone for status or destructive meaning.",
"Use flat neutral layers and precise borders before considering shadow; reserve shadow for true overlays and menus.",
"Use 44px targets on touch layouts even when desktop density is compact.",
"Write body copy in plain operational language and keep measure under 72 characters for instructions."
],
"dont": [
"Do not use huge overbold tight-tracked headings, gradient keyword emphasis, generic SaaS hero sections, or decorative bento icon cards.",
"Do not make beige the neutral foundation unless the product context explicitly requires paper records or archival warmth.",
"Do not merge brand accent and semantic status systems; blue action, info, success, warning, and error must remain distinct.",
"Do not nest rounded stat cards inside rounded panels or fill empty space with unrelated metrics.",
"Do not hide focus states, reduce table text below 12px, or use low-contrast gray for primary content.",
"Do not add pulsing dots, animated grids, glassmorphism, or sterile gradients to create artificial energy.",
"Do not use icons without labels for critical admin actions such as permission changes or audit exports."
]
}
}
related