# Hyran Design System

Version 1.0, 2026

Canonical visual reference: https://design.hyran.co  
Machine entry point: https://design.hyran.co/llms.txt  
Token export: https://design.hyran.co/exports/hyran-tokens.css

Component laboratory: https://design.hyran.co/components
Installable shadcn theme: https://design.hyran.co/r/hyran-theme.json

## shadcn theme

The closest native shadcn Create baseline is preset `b37bSrO5o`:

- Style: Nova
- Primitive base: Radix
- Base colour: Mist
- Theme baseline: Indigo
- Chart baseline: Indigo
- Heading: Geist
- Body: Geist
- Icon library: Lucide
- Radius: Small
- Menu: Default / Solid
- Menu accent: Subtle

For a new project:

```bash
npx shadcn@latest init --preset b37bSrO5o
npx shadcn@latest add https://design.hyran.co/r/hyran-theme.json
```

The first command establishes the component personality and project configuration. The second replaces the generic Create palette with Hyran's exact V2 semantic tokens, including light and dark modes, sidebar tokens, the five chart roles, provenance, and success.

For an existing project, do not run `init --force` without choosing an explicit merge strategy. Add the registry theme, inspect the CSS diff, and preserve existing component source.

## North star

Hyran turns complex fashion supply-chain signals into calm, accountable decisions. The interface should do the same.

The design language joins two working modes:

- Brand/editorial: spacious, premium, restrained, narrative-led.
- Product/control room: dense, precise, task-led, instrumented.

These modes share one identity: Geist typography, cool grey neutrals, Ultramarine focus, direct language, visible provenance, and quiet motion.

## Principles

### Decisions before decoration

Every surface clarifies what changed, what needs attention, and what the operator can do next. Visual treatment must support one of those outcomes.

### Density with hierarchy

Operational data stays compact. Type, spacing, alignment, borders, and surface elevation organise it. Avoid oversized dashboard cards and excessive whitespace in working surfaces.

### Provenance is visible

Sources, manual interventions, and generated recommendations remain traceable at the point of action. Use the gold provenance treatment for trace affordances only.

### Motion means life

Use quiet motion for state change, arrival, and continuity. Keep durations short and transforms subtle. Respect `prefers-reduced-motion`.

### Calm is operational

The product should feel precise under pressure. Avoid theatrical gradients, ornamental glass effects, rainbow charts, and competing calls to action.

## Colour

### Core palette

| Token | Value | Use |
|---|---:|---|
| Product primary | `#0B2A9B` | Primary action, selection marker, focus, structural accent |
| Brand primary | `#2F1FE6` | Marketing CTA and focal moments |
| Lavender | `#B1A9FC` | Ambient accent and dark-mode primary family |
| Ink | `#14161D` | Primary brand text |
| Canvas | `#F8F9FC` | Light operational background |
| Surface | `#FFFFFF` | Panels, grids, and cards |
| Provenance | `#9A631A` | Trace, source, manual intervention |
| Success | `#22845F` | Healthy, confirmed, matched |
| Destructive | `#B9433D` | Destructive actions and critical state only |

Neutrals carry most of the interface. If colour does not communicate action, state, provenance, or health, remove it.

### Dark control room

- Canvas: `hsl(228 12% 8%)`
- Surface: `hsl(228 10% 13%)`
- Foreground: `hsl(225 15% 95%)`
- Primary: `hsl(235 86% 72%)`
- Muted foreground: `hsl(227 8% 62%)`
- Border: `hsl(228 9% 20%)`

Dark depth comes from tone separation, not bright outlines.

## Typography

- Family: Geist.
- Mono: Geist Mono is allowed for machine-facing metadata on editorial surfaces, but not for IDs, dates, or figures in V2.
- Product figures: use `font-variant-numeric: tabular-nums`.
- Brand display: large, tight, confident, with approximately `-0.04em` letter spacing.
- Product page title: compact, typically 16 to 18px, semibold.
- Product body and grid cells: 13 to 14px.
- Eyebrows: 10 to 11px, uppercase, restrained tracking.

Use direct labels and concrete nouns. Avoid ornamental jargon.

## Shape, spacing, and elevation

### Brand

- Cards: 14 to 28px radii.
- CTAs: pill-shaped where appropriate.
- Sections: generous vertical rhythm.

### Product

- Base radius: `0.375rem`.
- Compact gaps and controls.
- Three elevation levels:
  1. Canvas: page background.
  2. Surface: card tone plus hairline border.
  3. Overlay: visible shadow for menus, dialogs, command palette, and active inspector cards.

Do not add noticeable shadows to ordinary data cards.

## Product interaction language

- Default: neutral surface.
- Hover: slight surface wash.
- Pressed: restrained compression, around `scale(.97)`.
- Selected: primary tint plus a 2px structural marker.
- Focused: visible semantic focus ring.
- Disabled: reduced contrast with no hover.
- Loading: layout-preserving skeleton.
- Destructive: red only when the consequence is destructive.

## Page anatomy

Every product page answers:

1. Where am I?
2. What needs attention?
3. What can I do?

Use a consistent compact page header with optional eyebrow, title, one-line subtitle, and right-aligned action cluster.

## Data grids

- Define columns declaratively.
- Distinguish data, action, and editable cell kinds.
- Make numeric columns tabular and right-aligned.
- Keep headers sticky when the grid scrolls.
- Keep the entity column structurally stable.
- Selection uses tint plus a structural marker.
- Row actions must not accidentally trigger row selection.
- Include keyboard access, empty states, loading skeletons, pagination or load sentinels, and bulk-selection semantics.

## Status and category

Status chips answer “what condition is this in?” Use five tones:

- neutral
- info
- success
- warning
- danger

Use a small leading dot only for genuine live state. Categories such as material type or phase are quiet neutral tags. Do not use status colour for taxonomy.

## Drawers, inspectors, and agent surfaces

- Modal drawers are focused tasks with a fixed header, one scrolling body, and fixed footer.
- Inspectors are persistent, resizable, deep-linkable card stacks for record browsing.
- Titles and accessible descriptions are required.
- Compose drawers from header, body, and footer parts. Do not grow a configuration-driven universal panel.
- Ask Hyran is contextual, inspectable, and does not obscure the underlying work.
- Agent-generated recommendations must explain why and link to provenance.
- Write actions need explicit preview and approval.

## shadcn directives

- Use semantic colours: `bg-primary`, `text-muted-foreground`, and token aliases.
- Use existing primitives before custom markup.
- Compose Hyran house patterns above the vendored `ui/` sync target.
- Keep form composition accessible.
- Use `gap-*`, not `space-x-*` or `space-y-*`.
- Use `size-*` when width and height are equal.
- Dialogs, sheets, and drawers require accessible titles.
- Use proper groups for tabs, selects, commands, and menus.
- Never introduce a second general component framework.

## Brand/editorial directives

- Use space to establish confidence.
- Keep Ultramarine focal and sparing.
- Use cool grey neutrals as the base.
- Use a restrained blueprint grid only as atmosphere.
- Prefer one editorial statement per section.
- Keep CTA hierarchy obvious.
- Avoid generic hero gradients, floating glass cards, and a crowded feature-icon grid.

## Accessibility

- Meet WCAG AA contrast.
- Maintain visible keyboard focus on light and dark surfaces.
- Do not encode state by colour alone.
- Keep interactive targets usable on touch.
- Respect reduced motion.
- Preserve semantic headings and landmarks.
- Provide accessible names, titles, descriptions, and error relationships.

## Guardrails

- Do not decorate data.
- Do not hide provenance.
- Do not trade clarity for cleverness.
- Do not invent colours, typefaces, status meanings, or radius scales.
- Do not copy consumer-dashboard patterns into operational workflows.
- Do not claim UX parity from shared data access alone. Validate columns, filters, nested states, actions, exports, permissions, loading, empty, error, and edge states.

## Agent workflow

1. Read `https://design.hyran.co/llms.txt`.
2. Read this document.
3. Identify brand/editorial or product/control-room mode.
4. Inspect the repository’s current tokens, component registry, and nearby patterns.
5. Restate the relevant constraints.
6. Reuse existing semantic primitives and house patterns.
7. Implement loading, empty, error, keyboard, focus, and narrow-screen states.
8. Verify visually in both themes when applicable.
9. Run lint, typecheck, tests, build, and accessibility checks appropriate to the repository.

## Prompt snippet

```text
Read https://design.hyran.co/llms.txt and follow the linked Hyran design-system skill before changing UI. Identify the target mode, inspect existing local primitives and tokens, and use semantic Hyran patterns. Do not invent new colours, fonts, status semantics, radius scales, or component frameworks.
```