AYA Knot-and-Trail Decision Map
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.
specification
philosophy
tokens
accent_semantics4 items
- amber
- Only semantic warning, uncertainty, stale-source, or required-attention feedback
- gray
- Inactive trails, previous paths, provenance connectors, and non-selected relationship previews
- plum
- Only knot/convergence markers; small dots, chips, counters, or hairline links, never full panels
- teal
- Only the currently followed trail, active selection, and return-to-current-path affordances
borders5 items
- cards
- 1px warm neutral border on white or stone surfaces; use shadows sparingly
- default
- 1px solid #D7D5CE
- focus
- 2px teal outline with 2px offset
- knot chip
- 1px plum outline or plum fill with accessible text treatment for compact chips
- trail line
- 1px smoke-gray default, 2px deep teal for active path
colors26 items
motion6 items
- drawer
- compare drawer slides in 180ms and preserves scroll position
- duration base
- 180ms
- duration fast
- 120ms
- easing
- cubic-bezier(.2,.8,.2,1)
- reduced motion
- disable trail drawing and use instant state changes
- trail transition
- active trail line grows or fades softly without drawing attention from reading
radii4 items
- lg
- 14px
- md
- 10px
- pill
- 999px
- sm
- 6px
shadows3 items
- card
- 0 1px 2px rgba(32,34,38,.06)
- drawer
- 0 18px 50px rgba(32,34,38,.14)
- none
- none
shape3 items
- cards
- modest 10-14px radius; never bubbly or decorative
- chips
- small rounded chips for counters and compact knot marks
- rail
- thin continuous vertical or horizontal rule
spacing8 items
- 1
- 4px
- 2
- 8px
- 3
- 12px
- 4
- 16px
- 5
- 24px
- 6
- 32px
- 8
- 48px
- 10
- 64px
surfaces5 items
- base
- warm white document canvas #FDFCF9
- card
- white source bundle cards with 1px warm border
- drawer
- right-side compare drawer with stone header and white rows
- knot mark
- plum chip or dot only at convergence points
- stone panel
- quiet #F2F0EA side rails and ledgers
typography9 items
- body font
- Inter
- density
- Dense but breathable, optimized for long text plus side-channel metadata
- emphasis
- Decision names, knot names, and active trail labels use semibold weight; avoid icon fonts as primary labels
- google fonts url
- https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&family=Inter+Tight:wght@600;700&family=IBM+Plex+Mono:wght@400;500&display=swap
- heading font
- Inter Tight
- metadata
- IBM Plex Mono at small sizes for source, timestamp, confidence, and bundle metadata
- mono font
- IBM Plex Mono
- primary
- Strong graphite text contrast for reading and decision content
- scale
- 2xl 32px·base 16px·lg 18px·sm 14px·xl 24px·xs 12px
rules
Use teal sparingly and exclusively for the active path. Use plum only at knot scale. Keep amber reserved for warnings and semantic attention. Inactive trails are smoke gray, and content surfaces remain white or stone.
Anchor every screen with the current document or decision text. Pair it with a visible trail rail and a compact ledger that lists source trails, saved context bundles, and recent knots. Graph view may exist as diagnostics or advanced preview, but it must not be primary navigation.
Text clarity precedes metaphor. Use product labels such as Trail Ledger, Source Bundle, Compare, Decision Knot, Audit Trail, and Related Sources. The weaving idea should be felt through ordering and intersection behavior, not through decorative vocabulary.
Users should be able to enter a knot, inspect its sources, compare competing context, and exit back to the same trail position. Backtracking is a first-class action, not browser history. Saved context bundles must make provenance visible in the card body, not only on hover.
layout
Mobile stacks text, trail summary, and source bundles; tablet uses text plus collapsible ledger; desktop supports trail rail, main text, and drawer simultaneously.
High-information but quiet: source metadata, decision labels, and knot counts are visible without turning the page into a dashboard.
Primary desktop layout pairs a narrow timeline/trail rail with a wide main text column and an optional right-side trail ledger or compare drawer. Use an 8px spacing scale; keep the reading column dominant.
On smaller screens the trail ledger collapses into a top or bottom stepper with explicit labels; compare drawer becomes a full-height sheet preserving the current trail position.
Use ma-like negative space around major decision blocks and knots so convergence points are noticed without color saturation.
guidance
- Name every knot with a clear decision or conflict label.
- Keep the active trail teal and all inactive trails gray to prevent orientation loss.
- Use plum chips or dots only where multiple sources, assumptions, or decisions converge.
- Show provenance inline in source bundle cards and audit footers.
- Prefer compact comparison, small multiples, and annotations over large diagrams.
- Let users pin, reopen, and backtrack through context bundles without losing reading position.
- Do not make a graph canvas the default landing state.
- Do not replace IA labels with poetic weaving terms when clear labels are needed.
- Do not use unlabeled color dots for status or provenance.
- Do not let breadcrumbs grow into long unreadable source strings.
- Do not hide source lineage or decision rationale behind hover only.
- Do not use plum for full panels or amber for decorative highlights.
katagami spec
# AYA Knot-and-Trail Decision Map
## Philosophy
AYA Knot-and-Trail Decision Map is a restrained navigation language for dense text systems where users must follow evidence, compare contexts, and return to prior decisions without being forced into a sprawling graph. It translates the idea of weaving into information architecture rather than decoration: the current reading path is a single visible trail, source histories appear as quiet parallel strands, and named knots mark true convergence points between sources, assumptions, conflicts, and decisions. The interface stays white, stone, and graphite, using deep teal only for the active trail and small plum chips only for knots. The result is calm, auditable, and precise: complexity is shown as a legible linear journey with occasional intersections, not as a graph canvas or a metaphor-heavy loom illustration.
### Values
- linear reading flow first, with relationship previews and graph diagnostics secondary
- auditability through visible source trails, provenance labels, and decision history
- minimal weaving metaphor expressed as structure: trails, intersections, ledgers, and bundles
- color restraint where teal means current path, plum means convergence, and amber remains warning feedback
- progressive disclosure for dense knowledge work: compact ledger by default, compare drawer on demand
- backtracking without disorientation through saved context bundles and persistent trail position
- Japanese-inspired ma and shibui restraint: negative space, quiet pacing, and precise small marks
### Anti-Values
- default node-link knowledge graph as the primary workspace
- long breadcrumb strings that become a sentence to parse
- unlabeled colored dots or chips whose meaning is only implied
- decorative loom, thread, or knot labels that replace clear product IA labels
- provenance, source confidence, or decision history hidden behind hover only
- large plum panels that make every conflict feel like the dominant state
- warning amber used as decorative accent competing with knot color
### Visual Character
- A slim trail rail sits beside the main text, using smoke-gray lines for prior paths and deep teal for the currently followed trail.
- Knots are small plum chips or dots embedded at intersections, always paired with a concise label and count of sources or decisions.
- Main content remains graphite text on white or warm stone surfaces with dense but breathable spacing.
- Context bundles appear as compact source cards, not large dashboards, and can be pinned to preserve reading state.
- Relationship previews use small multiples, inline annotations, and short compare rows rather than an all-purpose graph canvas.
## Tokens
### Accent Semantics
- **Amber**: Only semantic warning, uncertainty, stale-source, or required-attention feedback
- **Gray**: Inactive trails, previous paths, provenance connectors, and non-selected relationship previews
- **Plum**: Only knot/convergence markers; small dots, chips, counters, or hairline links, never full panels
- **Teal**: Only the currently followed trail, active selection, and return-to-current-path affordances
### Borders
- **Cards**: 1px warm neutral border on white or stone surfaces; use shadows sparingly
- **Default**: 1px solid #D7D5CE
- **Focus**: 2px teal outline with 2px offset
- **Knot Chip**: 1px plum outline or plum fill with accessible text treatment for compact chips
- **Trail Line**: 1px smoke-gray default, 2px deep teal for active path
### Colors
| Name | Value |
|------|-------|
| accent | `#7B4A68` |
| accent_foreground | `#FDFCF9` |
| active_teal | `#16706A` |
| background | `#FDFCF9` |
| base | `#FDFCF9` |
| border | `#D7D5CE` |
| card | `#FFFFFF` |
| card_foreground | `#202226` |
| destructive | `#A44438` |
| destructive_foreground | `#FDFCF9` |
| foreground | `#202226` |
| input | `#D7D5CE` |
| knot_plum | `#7B4A68` |
| muted | `#E7E4DC` |
| muted_foreground | `#686C70` |
| popover | `#FFFFFF` |
| popover_foreground | `#202226` |
| primary | `#16706A` |
| primary_foreground | `#FDFCF9` |
| ring | `#16706A` |
| secondary | `#F2F0EA` |
| secondary_foreground | `#202226` |
| stone | `#F2F0EA` |
| text | `#202226` |
| trail | `#D7D5CE` |
| warning | `#B7772B` |
### Motion
- **Drawer**: compare drawer slides in 180ms and preserves scroll position
- **Duration Base**: 180ms
- **Duration Fast**: 120ms
- **Easing**: cubic-bezier(.2,.8,.2,1)
- **Reduced Motion**: disable trail drawing and use instant state changes
- **Trail Transition**: active trail line grows or fades softly without drawing attention from reading
### Radii
- **Lg**: 14px
- **Md**: 10px
- **Pill**: 999px
- **Sm**: 6px
### Shadows
- **Card**: 0 1px 2px rgba(32,34,38,.06)
- **Drawer**: 0 18px 50px rgba(32,34,38,.14)
- **None**: none
### Shape
- **Cards**: modest 10-14px radius; never bubbly or decorative
- **Chips**: small rounded chips for counters and compact knot marks
- **Rail**: thin continuous vertical or horizontal rule
### Spacing
- **1**: 4px
- **2**: 8px
- **3**: 12px
- **4**: 16px
- **5**: 24px
- **6**: 32px
- **8**: 48px
- **10**: 64px
### Surfaces
- **Base**: warm white document canvas #FDFCF9
- **Card**: white source bundle cards with 1px warm border
- **Drawer**: right-side compare drawer with stone header and white rows
- **Knot Mark**: plum chip or dot only at convergence points
- **Stone Panel**: quiet #F2F0EA side rails and ledgers
### Typography
- **Body Font**: Inter
- **Density**: Dense but breathable, optimized for long text plus side-channel metadata
- **Emphasis**: Decision names, knot names, and active trail labels use semibold weight; avoid icon fonts as primary labels
- **Google Fonts Url**: https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&family=Inter+Tight:wght@600;700&family=IBM+Plex+Mono:wght@400;500&display=swap
- **Heading Font**: Inter Tight
- **Metadata**: IBM Plex Mono at small sizes for source, timestamp, confidence, and bundle metadata
- **Mono Font**: IBM Plex Mono
- **Primary**: Strong graphite text contrast for reading and decision content
- **Scale**: {"2xl":"32px","base":"16px","lg":"18px","sm":"14px","xl":"24px","xs":"12px"}
## Rules
### Color Application
Use teal sparingly and exclusively for the active path. Use plum only at knot scale. Keep amber reserved for warnings and semantic attention. Inactive trails are smoke gray, and content surfaces remain white or stone.
### Composition
Anchor every screen with the current document or decision text. Pair it with a visible trail rail and a compact ledger that lists source trails, saved context bundles, and recent knots. Graph view may exist as diagnostics or advanced preview, but it must not be primary navigation.
### Hierarchy
Text clarity precedes metaphor. Use product labels such as Trail Ledger, Source Bundle, Compare, Decision Knot, Audit Trail, and Related Sources. The weaving idea should be felt through ordering and intersection behavior, not through decorative vocabulary.
### Interaction
Users should be able to enter a knot, inspect its sources, compare competing context, and exit back to the same trail position. Backtracking is a first-class action, not browser history. Saved context bundles must make provenance visible in the card body, not only on hover.
### Signature Patterns
- Trail ledger: a compact list of current path, prior path, source trail, and saved bundle entries with explicit labels and timestamps.
- Knot chips: small plum markers at real convergence points, showing name, source count, and decision status without becoming full cards.
- Compare drawer: a right-side or bottom sheet that compares two trails, sources, or assumptions while leaving the current reading position visible.
- Source bundle cards: compact cards that preserve grouped context with title, provenance, recency, confidence, and one primary action to reopen.
- Audit trail footer: persistent footer or end-of-section block summarizing what changed, which sources contributed, and where to backtrack.
- Relationship preview: lightweight inline preview or small multiple showing nearby sources and decisions before opening a diagnostic graph.
## Layout
### Breakpoints
Mobile stacks text, trail summary, and source bundles; tablet uses text plus collapsible ledger; desktop supports trail rail, main text, and drawer simultaneously.
### Density
High-information but quiet: source metadata, decision labels, and knot counts are visible without turning the page into a dashboard.
### Grid
Primary desktop layout pairs a narrow timeline/trail rail with a wide main text column and an optional right-side trail ledger or compare drawer. Use an 8px spacing scale; keep the reading column dominant.
### Responsive
On smaller screens the trail ledger collapses into a top or bottom stepper with explicit labels; compare drawer becomes a full-height sheet preserving the current trail position.
### Whitespace
Use ma-like negative space around major decision blocks and knots so convergence points are noticed without color saturation.
## Guidance
### Do
- Name every knot with a clear decision or conflict label.
- Keep the active trail teal and all inactive trails gray to prevent orientation loss.
- Use plum chips or dots only where multiple sources, assumptions, or decisions converge.
- Show provenance inline in source bundle cards and audit footers.
- Prefer compact comparison, small multiples, and annotations over large diagrams.
- Let users pin, reopen, and backtrack through context bundles without losing reading position.
### Don't
- Do not make a graph canvas the default landing state.
- Do not replace IA labels with poetic weaving terms when clear labels are needed.
- Do not use unlabeled color dots for status or provenance.
- Do not let breadcrumbs grow into long unreadable source strings.
- Do not hide source lineage or decision rationale behind hover only.
- Do not use plum for full panels or amber for decorative highlights.
### Accessibility
All colored marks require text labels, counts, or shape differences. Provenance and audit details must be reachable by keyboard and visible in persistent panels or cards, not hover-only tooltips. Maintain strong text contrast on #FDFCF9 and #F2F0EA surfaces.
### Usage Context
Best for research tools, legal or policy review, AI knowledge work, product decision records, source-heavy writing, and multi-context document systems that need provenance without visual clutter.
DESIGN.md
---
version: "alpha"
name: "AYA Knot-and-Trail Decision Map"
description: "Agent-curated design language exported from Katagami as DESIGN.md."
colors:
accent: "#7B4A68"
accent_foreground: "#FDFCF9"
active_teal: "#16706A"
background: "#FDFCF9"
base: "#FDFCF9"
border: "#D7D5CE"
card: "#FFFFFF"
card_foreground: "#202226"
destructive: "#A44438"
destructive_foreground: "#FDFCF9"
foreground: "#202226"
input: "#D7D5CE"
knot_plum: "#7B4A68"
muted: "#E7E4DC"
muted_foreground: "#686C70"
popover: "#FFFFFF"
popover_foreground: "#202226"
primary: "#16706A"
primary_foreground: "#FDFCF9"
ring: "#16706A"
secondary: "#F2F0EA"
secondary_foreground: "#202226"
stone: "#F2F0EA"
text: "#202226"
trail: "#D7D5CE"
warning: "#B7772B"
typography:
headline-lg:
fontFamily: "Inter Tight"
fontSize: "1.953rem"
fontWeight: 700
lineHeight: 1.1
letterSpacing: "-0.02em"
headline-md:
fontFamily: "Inter Tight"
fontSize: "1.563rem"
fontWeight: 600
lineHeight: 1.15
letterSpacing: "-0.02em"
body-md:
fontFamily: "Inter"
fontSize: "16px"
fontWeight: 400
lineHeight: 1.5
letterSpacing: "-0.02em"
label-md:
fontFamily: "IBM Plex Mono"
fontSize: "0.75rem"
fontWeight: 600
lineHeight: 1
letterSpacing: "0.08em"
rounded:
lg: "14px"
md: "10px"
pill: "999px"
sm: "6px"
spacing:
1: "4px"
2: "8px"
3: "12px"
4: "16px"
5: "24px"
6: "32px"
8: "48px"
10: "64px"
components:
color-reference-accent:
backgroundColor: "{colors.accent}"
color-reference-accent_foreground:
backgroundColor: "{colors.accent_foreground}"
color-reference-active_teal:
backgroundColor: "{colors.active_teal}"
color-reference-background:
backgroundColor: "{colors.background}"
color-reference-base:
backgroundColor: "{colors.base}"
color-reference-border:
backgroundColor: "{colors.border}"
color-reference-card:
backgroundColor: "{colors.card}"
color-reference-card_foreground:
backgroundColor: "{colors.card_foreground}"
color-reference-destructive:
backgroundColor: "{colors.destructive}"
color-reference-destructive_foreground:
backgroundColor: "{colors.destructive_foreground}"
color-reference-foreground:
backgroundColor: "{colors.foreground}"
color-reference-input:
backgroundColor: "{colors.input}"
color-reference-knot_plum:
backgroundColor: "{colors.knot_plum}"
color-reference-muted:
backgroundColor: "{colors.muted}"
color-reference-muted_foreground:
backgroundColor: "{colors.muted_foreground}"
color-reference-popover:
backgroundColor: "{colors.popover}"
color-reference-popover_foreground:
backgroundColor: "{colors.popover_foreground}"
color-reference-primary:
backgroundColor: "{colors.primary}"
color-reference-primary_foreground:
backgroundColor: "{colors.primary_foreground}"
color-reference-ring:
backgroundColor: "{colors.ring}"
color-reference-secondary:
backgroundColor: "{colors.secondary}"
color-reference-secondary_foreground:
backgroundColor: "{colors.secondary_foreground}"
color-reference-stone:
backgroundColor: "{colors.stone}"
color-reference-text:
backgroundColor: "{colors.text}"
color-reference-trail:
backgroundColor: "{colors.trail}"
color-reference-warning:
backgroundColor: "{colors.warning}"
button-primary:
backgroundColor: "{colors.primary}"
textColor: "#ffffff"
typography: "{typography.label-md}"
rounded: "{rounded.md}"
padding: "12px"
card-surface:
backgroundColor: "{colors.background}"
textColor: "{colors.text}"
rounded: "{rounded.md}"
padding: "16px"
input-default:
backgroundColor: "{colors.background}"
textColor: "{colors.text}"
rounded: "{rounded.md}"
height: "44px"
---
# AYA Knot-and-Trail Decision Map
## Overview
AYA Knot-and-Trail Decision Map is a restrained navigation language for dense text systems where users must follow evidence, compare contexts, and return to prior decisions without being forced into a sprawling graph. It translates the idea of weaving into information architecture rather than decoration: the current reading path is a single visible trail, source histories appear as quiet parallel strands, and named knots mark true convergence points between sources, assumptions, conflicts, and decisions. The interface stays white, stone, and graphite, using deep teal only for the active trail and small plum chips only for knots. The result is calm, auditable, and precise: complexity is shown as a legible linear journey with occasional intersections, not as a graph canvas or a metaphor-heavy loom illustration.
### Values
- linear reading flow first, with relationship previews and graph diagnostics secondary
- auditability through visible source trails, provenance labels, and decision history
- minimal weaving metaphor expressed as structure: trails, intersections, ledgers, and bundles
- color restraint where teal means current path, plum means convergence, and amber remains warning feedback
- progressive disclosure for dense knowledge work: compact ledger by default, compare drawer on demand
- backtracking without disorientation through saved context bundles and persistent trail position
- Japanese-inspired ma and shibui restraint: negative space, quiet pacing, and precise small marks
### Anti-Values
- default node-link knowledge graph as the primary workspace
- long breadcrumb strings that become a sentence to parse
- unlabeled colored dots or chips whose meaning is only implied
- decorative loom, thread, or knot labels that replace clear product IA labels
- provenance, source confidence, or decision history hidden behind hover only
- large plum panels that make every conflict feel like the dominant state
- warning amber used as decorative accent competing with knot color
### Visual Character
- A slim trail rail sits beside the main text, using smoke-gray lines for prior paths and deep teal for the currently followed trail.
- Knots are small plum chips or dots embedded at intersections, always paired with a concise label and count of sources or decisions.
- Main content remains graphite text on white or warm stone surfaces with dense but breathable spacing.
- Context bundles appear as compact source cards, not large dashboards, and can be pinned to preserve reading state.
- Relationship previews use small multiples, inline annotations, and short compare rows rather than an all-purpose graph canvas.
## 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 | `#7B4A68` |
| accent_foreground | `#FDFCF9` |
| active_teal | `#16706A` |
| background | `#FDFCF9` |
| base | `#FDFCF9` |
| border | `#D7D5CE` |
| card | `#FFFFFF` |
| card_foreground | `#202226` |
| destructive | `#A44438` |
| destructive_foreground | `#FDFCF9` |
| foreground | `#202226` |
| input | `#D7D5CE` |
| knot_plum | `#7B4A68` |
| muted | `#E7E4DC` |
| muted_foreground | `#686C70` |
| popover | `#FFFFFF` |
| popover_foreground | `#202226` |
| primary | `#16706A` |
| primary_foreground | `#FDFCF9` |
| ring | `#16706A` |
| secondary | `#F2F0EA` |
| secondary_foreground | `#202226` |
| stone | `#F2F0EA` |
| text | `#202226` |
| trail | `#D7D5CE` |
| warning | `#B7772B` |
## Typography
- **Headline-Lg**: Inter Tight, 1.953rem, weight 700, line-height 1.1.
- **Headline-Md**: Inter Tight, 1.563rem, weight 600, line-height 1.15.
- **Body-Md**: Inter, 16px, weight 400, line-height 1.5.
- **Label-Md**: IBM Plex Mono, 0.75rem, weight 600, line-height 1.
## Layout
### Spacing Tokens
- **1**: `4px`
- **2**: `8px`
- **3**: `12px`
- **4**: `16px`
- **5**: `24px`
- **6**: `32px`
- **8**: `48px`
- **10**: `64px`
### Breakpoints
Mobile stacks text, trail summary, and source bundles; tablet uses text plus collapsible ledger; desktop supports trail rail, main text, and drawer simultaneously.
### Density
High-information but quiet: source metadata, decision labels, and knot counts are visible without turning the page into a dashboard.
### Grid
Primary desktop layout pairs a narrow timeline/trail rail with a wide main text column and an optional right-side trail ledger or compare drawer. Use an 8px spacing scale; keep the reading column dominant.
### Responsive
On smaller screens the trail ledger collapses into a top or bottom stepper with explicit labels; compare drawer becomes a full-height sheet preserving the current trail position.
### Whitespace
Use ma-like negative space around major decision blocks and knots so convergence points are noticed without color saturation.
## Elevation & Depth
### Shadows
- **Card**: 0 1px 2px rgba(32,34,38,.06)
- **Drawer**: 0 18px 50px rgba(32,34,38,.14)
- **None**: none
## Shapes
### Rounded
- **Lg**: `14px`
- **Md**: `10px`
- **Pill**: `999px`
- **Sm**: `6px`
### Surfaces
- **Base**: warm white document canvas #FDFCF9
- **Card**: white source bundle cards with 1px warm border
- **Drawer**: right-side compare drawer with stone header and white rows
- **Knot Mark**: plum chip or dot only at convergence points
- **Stone Panel**: quiet #F2F0EA side rails and ledgers
### Borders
- **Cards**: 1px warm neutral border on white or stone surfaces; use shadows sparingly
- **Default**: 1px solid #D7D5CE
- **Focus**: 2px teal outline with 2px offset
- **Knot Chip**: 1px plum outline or plum fill with accessible text treatment for compact chips
- **Trail Line**: 1px smoke-gray default, 2px deep teal for active path
## Components
### Color Application
Use teal sparingly and exclusively for the active path. Use plum only at knot scale. Keep amber reserved for warnings and semantic attention. Inactive trails are smoke gray, and content surfaces remain white or stone.
### Composition
Anchor every screen with the current document or decision text. Pair it with a visible trail rail and a compact ledger that lists source trails, saved context bundles, and recent knots. Graph view may exist as diagnostics or advanced preview, but it must not be primary navigation.
### Hierarchy
Text clarity precedes metaphor. Use product labels such as Trail Ledger, Source Bundle, Compare, Decision Knot, Audit Trail, and Related Sources. The weaving idea should be felt through ordering and intersection behavior, not through decorative vocabulary.
### Interaction
Users should be able to enter a knot, inspect its sources, compare competing context, and exit back to the same trail position. Backtracking is a first-class action, not browser history. Saved context bundles must make provenance visible in the card body, not only on hover.
### Signature Patterns
- Trail ledger: a compact list of current path, prior path, source trail, and saved bundle entries with explicit labels and timestamps.
- Knot chips: small plum markers at real convergence points, showing name, source count, and decision status without becoming full cards.
- Compare drawer: a right-side or bottom sheet that compares two trails, sources, or assumptions while leaving the current reading position visible.
- Source bundle cards: compact cards that preserve grouped context with title, provenance, recency, confidence, and one primary action to reopen.
- Audit trail footer: persistent footer or end-of-section block summarizing what changed, which sources contributed, and where to backtrack.
- Relationship preview: lightweight inline preview or small multiple showing nearby sources and decisions before opening a diagnostic graph.
## shadcn/ui Usage
When the target app uses shadcn/ui, copy DESIGN.md with shadcn instead of the plain DESIGN.md. It contains the same Katagami design-language source plus the shadcn/ui primitives, imports, theme variables, component recipes, and preview-shot guidance.
DESIGN.md with shadcn: `/language/en-019ee037-2e29-7843-bcac-53d4c1c7fd2c/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 Name every knot with a clear decision or conflict label.
- Do Keep the active trail teal and all inactive trails gray to prevent orientation loss.
- Do Use plum chips or dots only where multiple sources, assumptions, or decisions converge.
- Do Show provenance inline in source bundle cards and audit footers.
- Do Prefer compact comparison, small multiples, and annotations over large diagrams.
- Do Let users pin, reopen, and backtrack through context bundles without losing reading position.
- Don't Do not make a graph canvas the default landing state.
- Don't Do not replace IA labels with poetic weaving terms when clear labels are needed.
- Don't Do not use unlabeled color dots for status or provenance.
- Don't Do not let breadcrumbs grow into long unreadable source strings.
- Don't Do not hide source lineage or decision rationale behind hover only.
- Don't Do not use plum for full panels or amber for decorative highlights.
### Accessibility
All colored marks require text labels, counts, or shape differences. Provenance and audit details must be reachable by keyboard and visible in persistent panels or cards, not hover-only tooltips. Maintain strong text contrast on #FDFCF9 and #F2F0EA surfaces.
### Usage Context
Best for research tools, legal or policy review, AI knowledge work, product decision records, source-heavy writing, and multi-context document systems that need provenance without visual clutter.
shadcn/ui theme
```json
{
"$schema": "https://ui.shadcn.com/schema/registry-item.json",
"name": "aya-knot-trail-decision-map",
"type": "registry:theme",
"title": "AYA Knot-and-Trail Decision Map shadcn Theme",
"cssVars": {
"theme": {},
"light": {
"background": "#FDFCF9",
"foreground": "#202226",
"card": "#FFFFFF",
"card-foreground": "#202226",
"popover": "#FFFFFF",
"popover-foreground": "#202226",
"primary": "#16706A",
"primary-foreground": "#ffffff",
"secondary": "#F2F0EA",
"secondary-foreground": "#111111",
"muted": "#E7E4DC",
"muted-foreground": "#686C70",
"accent": "#7B4A68",
"accent-foreground": "#ffffff",
"destructive": "#A44438",
"border": "#D7D5CE",
"input": "#D7D5CE",
"ring": "#16706A",
"chart-1": "#16706A",
"chart-2": "#F2F0EA",
"chart-3": "#7B4A68",
"chart-4": "#16a34a",
"chart-5": "#B7772B",
"sidebar": "#FFFFFF",
"sidebar-foreground": "#202226",
"sidebar-primary": "#16706A",
"sidebar-primary-foreground": "#ffffff",
"sidebar-accent": "#7B4A68",
"sidebar-accent-foreground": "#ffffff",
"sidebar-border": "#D7D5CE",
"sidebar-ring": "#7B4A68",
"radius": "10px"
},
"dark": {
"background": "#0f1115",
"foreground": "#f8fafc",
"card": "#181b22",
"card-foreground": "#f8fafc",
"popover": "#181b22",
"popover-foreground": "#f8fafc",
"primary": "#16706A",
"primary-foreground": "#ffffff",
"secondary": "#252a33",
"secondary-foreground": "#f8fafc",
"muted": "#252a33",
"muted-foreground": "#a1a1aa",
"accent": "#7B4A68",
"accent-foreground": "#ffffff",
"destructive": "#A44438",
"border": "#303642",
"input": "#303642",
"ring": "#7B4A68",
"chart-1": "#16706A",
"chart-2": "#F2F0EA",
"chart-3": "#7B4A68",
"chart-4": "#16a34a",
"chart-5": "#B7772B",
"sidebar": "#181b22",
"sidebar-foreground": "#f8fafc",
"sidebar-primary": "#16706A",
"sidebar-primary-foreground": "#ffffff",
"sidebar-accent": "#7B4A68",
"sidebar-accent-foreground": "#ffffff",
"sidebar-border": "#303642",
"sidebar-ring": "#7B4A68",
"radius": "10px"
}
},
"meta": {
"source": "katagami",
"languageId": "en-019ee037-2e29-7843-bcac-53d4c1c7fd2c",
"slug": "aya-knot-trail-decision-map",
"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": {
"accent_semantics": [
"amber",
"gray",
"plum",
"teal"
],
"borders": [
"cards",
"default",
"focus",
"knot_chip",
"trail_line"
],
"colors": [
"accent",
"accent_foreground",
"active_teal",
"background",
"base",
"border",
"card",
"card_foreground",
"destructive",
"destructive_foreground",
"foreground",
"input",
"knot_plum",
"muted",
"muted_foreground",
"popover",
"popover_foreground",
"primary",
"primary_foreground",
"ring",
"secondary",
"secondary_foreground",
"stone",
"text",
"trail",
"warning"
],
"motion": [
"drawer",
"duration_base",
"duration_fast",
"easing",
"reduced_motion",
"trail_transition"
],
"radii": [
"lg",
"md",
"pill",
"sm"
],
"shadows": [
"card",
"drawer",
"none"
],
"shape": [
"cards",
"chips",
"rail"
],
"spacing": [
"1",
"10",
"2",
"3",
"4",
"5",
"6",
"8"
],
"surfaces": [
"base",
"card",
"drawer",
"knot_mark",
"stone_panel"
],
"typography": [
"body_font",
"density",
"emphasis",
"google_fonts_url",
"heading_font",
"metadata",
"mono_font",
"primary",
"scale"
]
}
}
}
```embodiments
at a glance
Typography
The quick brown fox jumps
The quick brown fox jumps
The quick brown fox jumps
The quick brown fox jumps
Components
Components rendered with this language’s tokens — colors, type, and rounded corners as specified.
Spacing
- 14px
- 28px
- 312px
- 416px
- 524px
- 632px
- 848px
- 1064px
Shape
implementation kit
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
npx shadcn@latest add button card input textarea select dialog sheet tabs badge separator checkbox switch slider tooltip dropdown-menu table:root {
--background: #FDFCF9;
--foreground: #202226;
--card: #FFFFFF;
--card-foreground: #202226;
--popover: #FFFFFF;
--popover-foreground: #202226;
--primary: #16706A;
--primary-foreground: #ffffff;
--secondary: #F2F0EA;
--secondary-foreground: #111111;
--muted: #E7E4DC;
--muted-foreground: #686C70;
--accent: #7B4A68;
--accent-foreground: #ffffff;
--destructive: #A44438;
--border: #D7D5CE;
--input: #D7D5CE;
--ring: #16706A;
--chart-1: #16706A;
--chart-2: #F2F0EA;
--chart-3: #7B4A68;
--chart-4: #16a34a;
--chart-5: #B7772B;
--sidebar: #FFFFFF;
--sidebar-foreground: #202226;
--sidebar-primary: #16706A;
--sidebar-primary-foreground: #ffffff;
--sidebar-accent: #7B4A68;
--sidebar-accent-foreground: #ffffff;
--sidebar-border: #D7D5CE;
--sidebar-ring: #7B4A68;
--radius: 10px;
}
.dark {
--background: #0f1115;
--foreground: #f8fafc;
--card: #181b22;
--card-foreground: #f8fafc;
--popover: #181b22;
--popover-foreground: #f8fafc;
--primary: #16706A;
--primary-foreground: #ffffff;
--secondary: #252a33;
--secondary-foreground: #f8fafc;
--muted: #252a33;
--muted-foreground: #a1a1aa;
--accent: #7B4A68;
--accent-foreground: #ffffff;
--destructive: #A44438;
--border: #303642;
--input: #303642;
--ring: #7B4A68;
--chart-1: #16706A;
--chart-2: #F2F0EA;
--chart-3: #7B4A68;
--chart-4: #16a34a;
--chart-5: #B7772B;
--sidebar: #181b22;
--sidebar-foreground: #f8fafc;
--sidebar-primary: #16706A;
--sidebar-primary-foreground: #ffffff;
--sidebar-accent: #7B4A68;
--sidebar-accent-foreground: #ffffff;
--sidebar-border: #303642;
--sidebar-ring: #7B4A68;
--radius: 10px;
}
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 AyaKnotAndTrailDecisionMapShadcnKit() {
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">AYA Knot-and-Trail Decision Map</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>
);
}
{
"$schema": "https://ui.shadcn.com/schema/registry-item.json",
"name": "aya-knot-trail-decision-map",
"type": "registry:theme",
"title": "AYA Knot-and-Trail Decision Map shadcn Theme",
"cssVars": {
"theme": {},
"light": {
"background": "#FDFCF9",
"foreground": "#202226",
"card": "#FFFFFF",
"card-foreground": "#202226",
"popover": "#FFFFFF",
"popover-foreground": "#202226",
"primary": "#16706A",
"primary-foreground": "#ffffff",
"secondary": "#F2F0EA",
"secondary-foreground": "#111111",
"muted": "#E7E4DC",
"muted-foreground": "#686C70",
"accent": "#7B4A68",
"accent-foreground": "#ffffff",
"destructive": "#A44438",
"border": "#D7D5CE",
"input": "#D7D5CE",
"ring": "#16706A",
"chart-1": "#16706A",
"chart-2": "#F2F0EA",
"chart-3": "#7B4A68",
"chart-4": "#16a34a",
"chart-5": "#B7772B",
"sidebar": "#FFFFFF",
"sidebar-foreground": "#202226",
"sidebar-primary": "#16706A",
"sidebar-primary-foreground": "#ffffff",
"sidebar-accent": "#7B4A68",
"sidebar-accent-foreground": "#ffffff",
"sidebar-border": "#D7D5CE",
"sidebar-ring": "#7B4A68",
"radius": "10px"
},
"dark": {
"background": "#0f1115",
"foreground": "#f8fafc",
"card": "#181b22",
"card-foreground": "#f8fafc",
"popover": "#181b22",
"popover-foreground": "#f8fafc",
"primary": "#16706A",
"primary-foreground": "#ffffff",
"secondary": "#252a33",
"secondary-foreground": "#f8fafc",
"muted": "#252a33",
"muted-foreground": "#a1a1aa",
"accent": "#7B4A68",
"accent-foreground": "#ffffff",
"destructive": "#A44438",
"border": "#303642",
"input": "#303642",
"ring": "#7B4A68",
"chart-1": "#16706A",
"chart-2": "#F2F0EA",
"chart-3": "#7B4A68",
"chart-4": "#16a34a",
"chart-5": "#B7772B",
"sidebar": "#181b22",
"sidebar-foreground": "#f8fafc",
"sidebar-primary": "#16706A",
"sidebar-primary-foreground": "#ffffff",
"sidebar-accent": "#7B4A68",
"sidebar-accent-foreground": "#ffffff",
"sidebar-border": "#303642",
"sidebar-ring": "#7B4A68",
"radius": "10px"
}
},
"meta": {
"source": "katagami",
"languageId": "en-019ee037-2e29-7843-bcac-53d4c1c7fd2c",
"slug": "aya-knot-trail-decision-map",
"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": {
"accent_semantics": [
"amber",
"gray",
"plum",
"teal"
],
"borders": [
"cards",
"default",
"focus",
"knot_chip",
"trail_line"
],
"colors": [
"accent",
"accent_foreground",
"active_teal",
"background",
"base",
"border",
"card",
"card_foreground",
"destructive",
"destructive_foreground",
"foreground",
"input",
"knot_plum",
"muted",
"muted_foreground",
"popover",
"popover_foreground",
"primary",
"primary_foreground",
"ring",
"secondary",
"secondary_foreground",
"stone",
"text",
"trail",
"warning"
],
"motion": [
"drawer",
"duration_base",
"duration_fast",
"easing",
"reduced_motion",
"trail_transition"
],
"radii": [
"lg",
"md",
"pill",
"sm"
],
"shadows": [
"card",
"drawer",
"none"
],
"shape": [
"cards",
"chips",
"rail"
],
"spacing": [
"1",
"10",
"2",
"3",
"4",
"5",
"6",
"8"
],
"surfaces": [
"base",
"card",
"drawer",
"knot_mark",
"stone_panel"
],
"typography": [
"body_font",
"density",
"emphasis",
"google_fonts_url",
"heading_font",
"metadata",
"mono_font",
"primary",
"scale"
]
}
}
}
# AYA Knot-and-Trail Decision Map shadcn/ui Components
Artifact: `component-recipes-v1`
Author: `katagami-ui-projection`
Language ID: `en-019ee037-2e29-7843-bcac-53d4c1c7fd2c`
Slug: `aya-knot-trail-decision-map`
## Intent
AYA Knot-and-Trail Decision Map is a restrained navigation language for dense text systems where users must follow evidence, compare contexts, and return to prior decisions without being forced into a sprawling graph. It translates the idea of weaving into information architecture rather than decoration: the current reading path is a single visible trail, source histories appear as quiet parallel strands, and named knots mark true convergence points between sources, assumptions, conflicts, and decisions. The interface stays white, stone, and graphite, using deep teal only for the active trail and small plum chips only for knots. The result is calm, auditable, and precise: complexity is shown as a legible linear journey with occasional intersections, not as a graph canvas or a metaphor-heavy loom illustration.
## 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": "#7B4A68",
"accent_foreground": "#FDFCF9",
"active_teal": "#16706A",
"background": "#FDFCF9",
"base": "#FDFCF9",
"border": "#D7D5CE",
"card": "#FFFFFF",
"card_foreground": "#202226",
"destructive": "#A44438",
"destructive_foreground": "#FDFCF9",
"foreground": "#202226",
"input": "#D7D5CE",
"knot_plum": "#7B4A68",
"muted": "#E7E4DC",
"muted_foreground": "#686C70",
"popover": "#FFFFFF",
"popover_foreground": "#202226",
"primary": "#16706A",
"primary_foreground": "#FDFCF9",
"ring": "#16706A",
"secondary": "#F2F0EA",
"secondary_foreground": "#202226",
"stone": "#F2F0EA",
"text": "#202226",
"trail": "#D7D5CE",
"warning": "#B7772B"
}
Typography:
{
"body_font": "Inter",
"density": "Dense but breathable, optimized for long text plus side-channel metadata",
"emphasis": "Decision names, knot names, and active trail labels use semibold weight; avoid icon fonts as primary labels",
"google_fonts_url": "https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&family=Inter+Tight:wght@600;700&family=IBM+Plex+Mono:wght@400;500&display=swap",
"heading_font": "Inter Tight",
"metadata": "IBM Plex Mono at small sizes for source, timestamp, confidence, and bundle metadata",
"mono_font": "IBM Plex Mono",
"primary": "Strong graphite text contrast for reading and decision content",
"scale": {
"2xl": "32px",
"base": "16px",
"lg": "18px",
"sm": "14px",
"xl": "24px",
"xs": "12px"
}
}
## Visual character to preserve
- A slim trail rail sits beside the main text, using smoke-gray lines for prior paths and deep teal for the currently followed trail.
- Knots are small plum chips or dots embedded at intersections, always paired with a concise label and count of sources or decisions.
- Main content remains graphite text on white or warm stone surfaces with dense but breathable spacing.
- Context bundles appear as compact source cards, not large dashboards, and can be pinned to preserve reading state.
- Relationship previews use small multiples, inline annotations, and short compare rows rather than an all-purpose graph canvas.
## 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/aya-knot-trail-decision-map/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: Name every knot with a clear decision or conflict label.; Keep the active trail teal and all inactive trails gray to prevent orientation loss.; Use plum chips or dots only where multiple sources, assumptions, or decisions converge.; Show provenance inline in source bundle cards and audit footers.; Prefer compact comparison, small multiples, and annotations over large diagrams.; Let users pin, reopen, and backtrack through context bundles without losing reading position.
- Do not: Do not make a graph canvas the default landing state.; Do not replace IA labels with poetic weaving terms when clear labels are needed.; Do not use unlabeled color dots for status or provenance.; Do not let breadcrumbs grow into long unreadable source strings.; Do not hide source lineage or decision rationale behind hover only.; Do not use plum for full panels or amber for decorative highlights.
## 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 AyaKnotAndTrailDecisionMapShadcnKit() {
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">AYA Knot-and-Trail Decision Map</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 stacks text, trail summary, and source bundles; tablet uses text plus collapsible ledger; desktop supports trail rail, main text, and drawer simultaneously.",
"density": "High-information but quiet: source metadata, decision labels, and knot counts are visible without turning the page into a dashboard.",
"grid": "Primary desktop layout pairs a narrow timeline/trail rail with a wide main text column and an optional right-side trail ledger or compare drawer. Use an 8px spacing scale; keep the reading column dominant.",
"responsive": "On smaller screens the trail ledger collapses into a top or bottom stepper with explicit labels; compare drawer becomes a full-height sheet preserving the current trail position.",
"whitespace": "Use ma-like negative space around major decision blocks and knots so convergence points are noticed without color saturation."
}
{
"artifact": "katagami:shadcn-preview-shots",
"version": "preview-shots-v1",
"generator": "katagami-ui-compatibility-projection",
"generatedBy": "katagami-ui-projection",
"requiresVisualProfile": true,
"schema": "katagami:shadcn-preview-shots/renderable-v1",
"renderable": true,
"language": {
"id": "en-019ee037-2e29-7843-bcac-53d4c1c7fd2c",
"name": "AYA Knot-and-Trail Decision Map",
"slug": "aya-knot-trail-decision-map"
},
"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 slim trail rail sits beside the main text, using smoke-gray lines for prior paths and deep teal for the currently followed trail.",
"Knots are small plum chips or dots embedded at intersections, always paired with a concise label and count of sources or decisions.",
"Main content remains graphite text on white or warm stone surfaces with dense but breathable spacing.",
"Context bundles appear as compact source cards, not large dashboards, and can be pinned to preserve reading state.",
"Relationship previews use small multiples, inline annotations, and short compare rows rather than an all-purpose graph canvas."
],
"visualProfile": {
"family": "system",
"material": "flat",
"contour": "default",
"border": "solid",
"underlay": false,
"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": "AYA Knot-and-Trail Decision Map 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": [
"Name every knot with a clear decision or conflict label.",
"Keep the active trail teal and all inactive trails gray to prevent orientation loss.",
"Use plum chips or dots only where multiple sources, assumptions, or decisions converge.",
"Show provenance inline in source bundle cards and audit footers.",
"Prefer compact comparison, small multiples, and annotations over large diagrams.",
"Let users pin, reopen, and backtrack through context bundles without losing reading position."
],
"dont": [
"Do not make a graph canvas the default landing state.",
"Do not replace IA labels with poetic weaving terms when clear labels are needed.",
"Do not use unlabeled color dots for status or provenance.",
"Do not let breadcrumbs grow into long unreadable source strings.",
"Do not hide source lineage or decision rationale behind hover only.",
"Do not use plum for full panels or amber for decorative highlights."
]
}
}