Getting started

How to use this kit

This kit does not replace the official Design System (Storybook). It's the prototype-flavored mirror: same tokens, same components visually, but focused on mockup speed.

For designers and PMs

When you need to build a prototype of a flow — a new risk form, a reports view, a confirmation modal — copy the components from here. Each one ships with code ready to paste into your local prototype (or hand to Claude to assemble).

For your AI (Claude / Cursor / Copilot)

This kit is designed to be read by AIs — not only by humans. Every component page + .claude/components.json entry is structured for machine consumption. When you point your AI at this repo, it should follow a 3-step flywheel: search the kit first, create only if nothing fits, then feed the good new stuff back so the kit grows.

1
Search first

Before writing anything new, your AI must exhaust the kit. Parse .claude/components.json (fast, structured — one query resolves 'which component + which recipe' against the purpose + triggers fields). If a match exists, use the recipe snippet as-is. If it's approximate, compose via the composeWith list. Fall back to reading src/app/components/<name>/page.tsx only when the manifest is not enough. Never create if something existing fits — even loosely.

2
Create only when nothing fits

If the exhaustive search comes up empty, your AI should generate the new component under src/components/ui/<name>.tsx following the same shadcn + Radix + forwardRef + cn() pattern as the existing atoms. All Yuno conventions apply:

  • Semantic tokens only (var(--foreground), bg-card, border-input, text-muted-foreground) — never hardcoded hex.
  • Radius from the 9-token Yuno scale (rounded-none / xs / sm / md / lg / xl / 2xl / 3xl / 4xl / full) — never rounded-[Xpx].
  • Shadows from the 7-token scale (shadow-2xs / xs / sm / md / lg / xl / 2xl) — never on Input / Select / Textarea / DatePicker triggers.
  • Phosphor Icons only, weight='light' by default, weight='fill' for active/selected — never thin / regular / bold / duotone.
  • Geist Sans only across the Dashboard — never Geist Mono in product UI.
  • Font weights: normal / medium / semibold / bold, each with a specific role (see typography foundation).
  • Never variant='destructive' on Button — routine deletes use Primary inside a Dialog; clarity comes from copy, not from red.
  • No em-dashes in user-facing copy (both EN and ES).
  • Sentence case for labels and section titles; toast success copy ends with 'successfully.'
  • Document the new component with the same structure as existing pages: Anatomy + Recipes + Import + PropsTable + Related. Add a matching entry in .claude/components.json with import + variants + states + recipes[] + composeWith + forbiddenPatterns.
3
Feed good ones back to the kit

The kit grows via this loop. If the new component your AI generated is well-scoped, follows the conventions above, and would help more than one prototype, elevate it: open a PR against yuno-dashboard-prototype-kit with the component + its docs + the manifest entry. Leonardo or Juan Pablo Turina review; on merge, the auto-deploy to Railway makes it available to every prototype that reads the kit next. Every reused component is one less thing every future AI has to reinvent.

Prompt starters

Copy any of these when you kick off a new prototype with your AI. Replace the {curly-brace} placeholders with your own context. Focus on what you need — your AI will handle the technical rules from the kit.

Start a new prototype
I'm building a prototype for {section or feature} of the Yuno Dashboard. Use the yuno-dashboard-prototype-kit repo as the base. First check if the kit already has a template for {section or feature} (like base-checkout-builder or base-reconciliation). If yes, fork that one, it's the official starting point maintained by that section's PM. If not, fork templates/base (the Home) and add the feature at its own route. Reuse existing components and follow the Yuno conventions (colors, icons, spacing, no red destructive buttons). Before writing any code, show me the plan.
Compose a specific screen
I need a {screen type — e.g. settings page, list view with filters, wizard, empty state} for {feature name}. Use the yuno-dashboard-prototype-kit as the base: keep the Sidebar + TopBar shell and reuse the existing atoms and organisms (Table, Pagination, Card, Form, etc.). Only compose new pieces if nothing in the kit fits. Show me the layout before writing code.
Add a specific pattern
I need a {pattern — e.g. feature tutorial, delete confirmation, plan picker, row actions menu} inside {surface}. Look it up in yuno-dashboard-prototype-kit and use the recipe that already exists. If nothing is an exact match, tell me the closest option and how you'd adapt it before creating anything new.
Audit an existing prototype
Review this prototype: {path}. Compare it against the yuno-dashboard-prototype-kit conventions (colors, iconography, radius, spacing, forbidden patterns) and give me a punch list of what's aligned and what should change, ordered by impact.

For devs

This kit is not imported as a package.
Prototypes are illustrative. When a flow reaches production, take the structure and composition and swap for the official DS components (Storybook) — which is already wired to the monorepo with hover overrides, neutral vs slate tokens, and other established decisions.

Copying a component

On any component page you'll see examples with a Copy button at the top right of the code block. Paste into your project assuming you already have shadcn base installed (cn() utility, Tailwind, and radix primitives).

Example
<Button>Continue</Button>
<Button variant="outline">Cancel</Button>

Contributing new components

When creating a Yuno-specific component on top of shadcn (e.g. currency selector, transaction card), add it under src/components/ui/ and document it with the same format: Anatomy → When to use → Do/Don't → Examples.