---
name: hyran-design-system
description: Build or review Hyran interfaces using the canonical brand, V2 control-room design language, UX principles, tokens, and component directives.
---

# Hyran Design System

Use this skill for any Hyran website, application surface, UI component, visual review, Storybook story, or agent-generated interface.

## Required reading

Read these resources completely before acting:

1. `references/design-system.md`
2. `references/tokens.css`
3. `https://design.hyran.co/r/hyran-theme.json` when installing or reviewing a shadcn theme.

When network access is available, treat `https://design.hyran.co/llms.txt` as the canonical entry point and check whether the published contract is newer than this export.

## Workflow

1. Identify the working mode:
   - Brand/editorial for public narrative and marketing.
   - Product/control room for authenticated operational work.
2. Inspect the target repository’s `AGENTS.md`, current CSS tokens, `components.json`, and nearby components.
3. State the Hyran constraints relevant to the task.
4. Reuse existing components and semantic tokens before creating new primitives.
5. Implement the complete interaction contract: default, hover, pressed, selected, focus, disabled, loading, empty, error, and destructive states as applicable.
6. Keep provenance visible for data, manual changes, AI findings, and agent actions.
7. Validate narrow screens, keyboard operation, accessible names, contrast, reduced motion, and both V2 themes where applicable.
8. Run the strongest local verification available.

## shadcn baseline

- Create preset: `b37bSrO5o`
- Style: Nova
- Base: Radix
- Base colour: Mist
- Theme baseline: Indigo
- Font: Geist
- Icons: Lucide
- Radius: Small

For a new project, initialise the baseline and then apply the exact Hyran registry theme:

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

Do not treat the preset as the whole design system. The registry supplies exact appearance. This skill supplies composition, behaviour, UX judgement, accessibility, and verification.

## Hard rules

- Do not invent a new palette, font, radius scale, status taxonomy, or component framework.
- Use Geist. Product figures use tabular numerals, not monospace.
- Ultramarine means action and structure.
- Lavender is an ambient accent.
- Gold means provenance or manual intervention.
- Green means healthy or confirmed.
- Red means destructive or critical only.
- Product UI uses canvas, surface, and overlay elevation.
- Noticeable shadow is reserved for overlays.
- Every product page answers where am I, what needs attention, and what can I do.
- Use direct language and concrete labels.
- If it feels like a generic SaaS dashboard, revisit the hierarchy and semantics.

## Handoff

Report:

- Mode selected.
- Existing primitives reused.
- New system decisions, if any, with justification.
- Interaction and accessibility states verified.
- Commands and visual checks run.