Get started

Aura is an agentic design system for product UI. People browse this site. Coding agents read the same decisions as files: DESIGN.md, Cursor rules, skills, and the registry source. The components are React, built on Radix primitives. The tokens are the CSS those components already use. An agent can build a screen by following those files.

You own the code. Aura is distributed in shadcn mode: the CLI copies component source into your app. Registry items are addressed as @aura/button, @aura/card, and the rest of the catalog.

Aura specifies product UI. A writing voice and a Figma library are not specified yet; those foundation pages say so and stop. Do not invent the missing part. Use the decisions that are written down.

DESIGN.md holds the narrative spec and the long tables. The Aura skill at .agents/skills/aura/ holds the design guardrails. Always-on process rules live in .agents/rules/ and load through the .cursor/rules symlink. Other skills are the procedures. When they disagree, follow DESIGN.md and the component source, then fix the page that drifted.

What to open

The job picks the file.

Install

New Next.js app:

pnpm dlx @aura-design/cli@latest init

App that already has a package.json:

pnpm dlx @aura-design/cli@latest setup

Both commands write components.json with the @aura registry, generate light and dark accent and gray scales into globals.css, and add @aura/class-names, @aura/page-get-starter, @aura/css-main, @aura/rules, @aura/skill-aura, and @aura/skills. @aura/rules includes root DESIGN.md and the always-on process rules. @aura/skill-aura is the design skill at .agents/skills/aura/. Blueprint then scaffolds the feature map, the forms stack, the shadcn skill, and gdp-ts proofs.

Install the design skill on its own:

pnpm dlx shadcn@latest add @aura/skill-aura

pnpm dlx skills add somosgented/aura-design-system --skill aura

Add one component:

pnpm dlx shadcn@latest add @aura/button

There is no command that adds every component. Names are listed at all.txt. Command flags live on the CLI page. The existing-app notes live on Installation.

How an agent starts

Read before you write UI.

1. In the Aura monorepo, open root AGENTS.md, then root DESIGN.md.
2. In a consumer app, open root DESIGN.md and .agents/skills/aura/SKILL.md. Always-on process rules are in .cursor/rules/ (a symlink to .agents/rules/). If they are missing, run pnpm dlx @aura-design/cli@latest setup or follow the agent blueprint.
3. Open the agent harness and pick the layer for the job. A rule is a limit. A skill is the steps. Follow both.
4. Install the component (pnpm dlx shadcn@latest add @aura/button, swapping in the registry name) and use its variants. Layout and width at the call site are fine. Padding, color, and type belong on the component.
5. After UI edits, run the project lint. @shadcn/lint flags spacing off the 13px scale, raw palette colors, and restyle of a design-system component. The verify-aura-ui skill is that loop.

Agent harness

The harness is what an agent reads before it edits. Aura's own files and skills ship with the kit. Poteto mode comes from the Cursor marketplace. Design, motion, and React performance audits are installed for a review and left uncommitted. Where an audit disagrees with DESIGN.md or the Aura skill, Aura wins.

Own files

Blueprint also installs the upstream shadcn skill at .agents/skills/shadcn (pnpm dlx skills add shadcn/ui). Use it for the CLI, registry search, and presets. The Aura skill wins on icons, forms, spacing, typography, and restyle.

Consumer skills

@aura/skills installs these under .cursor/skills/. They are the procedures a consumer app gets from the registry.

Monorepo skills

These two stay in this repository. They are not part of @aura/skills, and sync-skills does not publish them.

Poteto mode

Poteto mode is Lauren Tan's pstack workflow: playbooks for a bug, a feature, a refactor, or an investigation, with a visible task list and evidence before the work is called done. The entry points are /setup-pstack and /poteto-mode.

Both commands come from the Cursor marketplace plugin. They are not vendored in this repo, and aura blueprint does not install them. Humans enable the plugin in Cursor desktop (/add-plugin pstack, then /setup-pstack). A cloud agent may not see the plugin. Aura rules, DESIGN.md, and lint still apply inside a /poteto-mode run.

Install, the trust model, and example prompts: pstack.

gdp-ts

gdp-ts is Guillermo Rauch's proof-carrying authorization. A sensitive function demands a proof about the exact ids it receives. The typechecker rejects a missing proof, a proof about a different user or project, or a raw id.

aura init, aura setup, and aura blueprint install it. Blueprint adds @gdp-ts/core, spreads the ESLint preset, installs the skill with npx skills add rauchg/gdp-ts --skill gdp-ts -a cursor -y --copy (it lands at .agents/skills/gdp-ts/), and writes starter proofs: session, org role, project role, plan entitlement, and deleteProject. The skill is not in the Aura registry. Do not cast a proof. CI is typecheck plus lint.

Practice and the starter files: gdp-ts.

Feature map

The feature map is the only project documentation. One short note per feature lives under wiki/obsidian-*/Feature-Map/, shown as a table by Feature-Map.base. The folder suffix is the package.json name with its first segment stripped. Aura's vault is wiki/obsidian-aura-design-project/Feature-Map/.

The rule is .agents/rules/feature-map.mdc, loaded through the .cursor/rules symlink. The procedure is skill update-feature-map. When you open or update a PR, update the note of each feature that PR changes, inside that PR. Code is the source of truth while you work. Do not keep a progress log, and do not write secrets into notes. Name environment variables only.

Blueprint creates the vault, the rule, and the skill.

Brand images

generate-brand-images is the Gemini skill in @aura/skills. Use it when a landing page, hero, or marketing page needs images that match the product identity.

It reads wiki/obsidian-*/Bootstrap.md and 01-Identity/. Image identity is ready only when the notes name a medium, a palette and lighting, composition or motifs, and exclusions. The script reads GOOGLE_API_KEY or GEMINI_API_KEY from .env. Name those variables. Do not print or commit the value. Blueprint writes a starter 01-Identity/Image-Identity.md and the skill.

Audits you install

Emil Kowalski's design and animation reviews, and Vercel's React performance review, are not part of Aura. Nothing in init, setup, or blueprint installs them, and no Aura rule loads them. Install one from upstream when you want that audit, run it, apply the findings you accept, and leave the folder uncommitted. aura blueprint deletes the Emil and Vercel copies an older CLI wrote into .cursor/skills/ and .agents/skills/.

Design and motion, from emilkowalski/skills:

npx skills add emilkowalski/skills \
  --skill emil-design-eng \
  --skill review-animations \
  --skill improve-animations \
  --skill find-animation-opportunities \
  -a cursor -y --copy

Invoke one by name, for example /review-animations on the current diff. The audit returns findings. It does not edit the code.

React performance, from vercel-labs/agent-skills. The installed name is vercel-react-best-practices. It checks waterfalls, bundle size, server work, and re-renders. In an Aura app, form validation stays validateFormData with an ajv JSON Schema.

npx skills add vercel-labs/agent-skills --skill vercel-react-best-practices -a cursor -y --copy

/vercel-react-best-practices Audit this screen and its server actions.

This is a separate gate from Aura's visual lint. Full catalog, the findings shape, and how to remove a skill: Audits. The WorkOS skill is the same kind of optional audit. That page has its install command.

Visual lint

@shadcn/lint is the machine check for Aura's Tailwind policy: spacing on the 13px scale, accent and gray tokens instead of a raw palette, and no restyle of a design-system component from the call site. Rules and DESIGN.md say what to do. Lint names the fix.

@aura/eslint-shadcn-lint installs eslint.aura-shadcn.mjs. The matching agent text is .agents/skills/aura/rules/lint.md. After UI edits, run the project's pnpm lint. Skill verify-aura-ui is that loop. This lint ships with Aura. It is not the Vercel performance skill above.

Detail: Lint.

Rules

These are the constraints already written in DESIGN.md and the Aura skill. Feature map and comment policy stay always-on rules. The linked page is the full text.

Spacing

--spacing is 13px. A utility is the number times 13, so p-4 is 52px and gap-0.5 is 6.5px. Use half-step increments: 1, 1.5, 2, 2.5. Map about 20px to 1.5 (19.5px). Put every section in a container. Prefer five container types or fewer.

The 4px Tailwind default is the wrong density for Aura, and a one-off pixel value leaves the scale.

Aura skill · Layout

Color

Parallel accent and gray scales, steps 1–12, plus alpha variants --accent-a1 through --accent-a12 and the gray equivalents. Prefer a semantic token when one exists (--primary, --accent-surface, --accent-contrast).

Steps 11 and 12 target APCA Lc 60 and Lc 90 on a step 2 background. On a transparent default, hover may use step 3. Production UI consumes tokens. Theme seeds stay in the theme file.

Aura skill · Color foundations

Typography

Primary type uses clamp() of --min, --val, and --max through h1–h6, .h1–.h6, p, and .p. blockquote shares the h4 scale. --min and --max are in rem. Large headings sit around a 1.1–1.3 line-height.

text-sm and text-xs are for fixed utility and meta text. Editable input, textarea, and select stay at 17px or larger. Docs set the root to 17px, so 1rem already meets that floor. The floor is global CSS, because a field under about 16px makes mobile browsers zoom on focus.

Aura skill · Typography foundations

Icons

Default library is @radix-ui/react-icons. Every icon gets className="icon". Size follows the type (icon, icon h4, icon h1). The container's gap separates an icon from its label. Own rows use gap-0.5. Button and Badge already own that gap, so an icon inside them takes no extra gap and no horizontal margin. ml-auto and mr-auto are only for pushing an item to the far side.

Aura skill · Icons

Motion

Honor prefers-reduced-motion with a reduced variant. Prefer CSS @theme animation tokens and @keyframes in @layer components. Animate transform and opacity. Accordion and collapsible height may use the Radix content-height variable. Enter and exit content with opacity and scale(). Overlays can use opacity alone. Set transform-origin where the motion physically starts. Hover and active may use scale(1.03) and scale(0.97). Keep steps near 250ms: tooltips ease-in-out, dialogs cubic-bezier(0.16, 1, 0.3, 1), accordion ease, buttons cubic-bezier(0.4, 0, 0.6, 1). Motion should explain cause and effect.

Aura skill · Motion

Accessibility

Interactive components ship keyboard operable, with a visible focus, an accessible name, and a correct role. Focus rings use step 8 or --aura-outline. The contrast targets are the color steps above. Touch targets use the 13px scale. Narrow navigation collapses into a sheet or drawer.

Accessibility · Aura skill

Registry and components

Public component APIs grow by additive props and variants. A breaking change is named in the PR. Appearance changes go through variants and sizes. className on a design-system component is for layout and width. Form controls (Input, Textarea, SelectTrigger, MaskInput, SegmentedInput) own their padding. Compose triggers with Radix asChild. Keep the Ladle story in sync with the public API.

@shadcn/lint checks this in the app: no arbitrary spacing, no raw palette colors, no restyle, no horizontal margin on an icon inside Button or Badge.

Components · Lint · Aura skill

Forms

useFormDynamic for state, Form and FormField for UI, validateFormData for ajv JSON Schema. Submit to a server action that re-validates with the same schema.

Forms · Aura skill · skill aura-forms

Product principles

Build for perception and operability. One voice with the user. A component should save the next person from rebuilding it. The user can change their mind. Complex products should still feel familiar.

Aura skill

Docs and comments

The only project documentation is the feature map in the Obsidian vault, updated in the PR that changes a feature. Fix a workaround in the code. A comment is for an external constraint this repo cannot change, a directive, a license, or generated code.

Feature map · No comments

Where to go next

• Handbook — how styling, motion, composition, and customization are wired.
• Taste — spacing, color, and type tokens on one page.
• Namespaces and Registry — how @aura/button resolves.
• Lint — the @shadcn/lint policy Aura ships.
• gdp-ts — the proofs blueprint installs for sensitive functions.

Questions

How do I pull upstream updates?

Add the component again with pnpm dlx shadcn@latest add @aura/button. Run setup in an existing app to refresh components.json, the color scales, DESIGN.md, the rules, and the skills. You can also copy a file from the GitHub repository.

Where do the numbers live?

Foundations for people. DESIGN.md and the Aura skill for agents. They describe one system.