For AI

---
name: enma-design
description: Design UI in Enma, Manish Mandal's design system with one core and six themes (Graphite, Glass, Paper, Mineral, Enamel, Ember). Use whenever you build, mock up or review a screen, component, landing page or Claude artifact that should look like Enma, when you pick a theme for a project, or when the user mentions Enma.
---

# Enma design

Enma is one core (spacing, type scale, components, states, motion, accessibility, rules) with six themes on top. A theme changes only the surface: color, fonts, radius, depth and how presses feel. Every screen should feel calm, precise and a little bit crafted.

## When to use this skill

- Building any UI for one of Manish's projects: React and Next.js apps, React Native, Chrome and VS Code extensions, freelance work, Claude artifacts.
- Making a mockup or prototype "in Enma".
- Reviewing a screen against Enma's rules.

For project setup, states, accessibility and the definition of done, also use the `enma-frontend` skill.

## 1. Pick the theme

Use the default for the project type. Override only with a reason, and write the decision down (`UI: Enma · ember · dark (home), toggle: no`).

| Project type                                    | Theme      | Home mode |
| ----------------------------------------------- | ---------- | --------- |
| B2B SaaS, dev tools, dashboards, internal tools | `graphite` | dark      |
| Consumer iOS-style apps, lifestyle, wellness    | `glass`    | light     |
| Learning, reading, writing, content             | `paper`    | light     |
| Finance, premium, trust-heavy, client work      | `mineral`  | light     |
| Playful side projects, landing pages, social    | `enamel`   | light     |
| Fitness, media, night-time use                  | `ember`    | dark      |

Every theme has light and dark; use the home mode unless the product needs a toggle. A project may change only three things: the accent color, the display font and the radius dial. Anything bigger is a new theme in the system. Details: [references/themes.md](references/themes.md).

## 2. Follow the core rules

- **One hero per screen:** a hero card with the big number, or a display headline. Everything else stays quiet.
- **One spark per view:** `--e-accent` marks one or two things (the highlighted bar, a status dot, the active tab). Never a background.
- **One primary button per view.** Siblings are `secondary` or `ghost`.
- **Numbers are the signature:** key figures use `Stat` in the theme's number face with tabular figures; units sit outside the number ("12,480 kg"); amounts right-align in tables.
- **Group with tone, not lines:** `raised` panels inside `surface` cards. Hairlines separate rows and table cells only (Paper is the exception: it is built from rules).
- **Smooth corners that nest:** `xl` frame, `lg` card, `md` group, `sm` input.
- **Physical motion, used sparingly:** presses spring back, numbers count up and bars grow once on first view, nothing loops, everything is instant under reduced motion.
- **Density follows the surface:** mobile is comfortable (44px targets, `lg` buttons, 16 to 20px padding); B2B is compact (`sm` toolbar controls, 13px table text, 12px labels).

## 3. Use tokens and roles, never raw values

Style everything with the `--e-*` roles, which always point at the active theme: `--e-bg`, `--e-surface`, `--e-raised`, `--e-field`, `--e-line`, `--e-line-strong`, `--e-ink`, `--e-ink-2`, `--e-primary`, `--e-on-primary`, `--e-accent`, `--e-on-accent`, `--e-accent-ink`, `--e-accent-soft`, `--e-positive`, `--e-positive-soft`, `--e-negative`, `--e-negative-soft`, `--e-hero`, `--e-on-hero`, `--e-on-hero-2`, `--e-track`, `--e-focus`, radius `--e-r-sm|md|lg|xl|control`, `--e-shadow-card`, fonts `--e-font-display|body|num|meta`. Shared scales: `--space-*`, `--control-sm|md|lg`, `--touch-min`, `--duration-*`, `--easing-*`. What each role means and the type scale: [references/tokens.md](references/tokens.md).

## 4. Build from components

Use the existing components before writing custom UI: `EnmaRoot`, `Button`, `IconButton`, `Icon`, `Badge`, `Card`, `Stat`, `Bars`, `LineChart`, `Sparkline`, `Donut`, `ListGroup`, `Table`, `TextField`, `Switch`, `Checkbox`, `SegmentedControl`, `TabBar`, `Avatar`, `Progress`, `Toast`. When to use each: [references/components.md](references/components.md). Without React (HTML, artifacts, other frameworks), use the class recipes: [references/recipes.md](references/recipes.md).

Missing something (dialog, menu, popover, combobox)? Build it on an accessible primitive (Radix UI or React Aria on web) and style it with Enma roles.

## 5. Write in Enma's voice

- Sentence case everywhere. Verbs first on actions: "Start workout", "New invoice", "Export".
- Say the outcome: "Invoice sent", "Saved". Never "successfully", "please" or exclamation marks.
- Errors say what happened and what to do, in one sentence: "The card was declined. Try another."
- Numbers carry units and context: "+12.4% this month", "4 × 8 · 80 kg".
- Placeholders are real examples ("Acme Labs"), not "e.g." or a repeat of the label.
- Status is always a word too ("Paid", "Overdue"), never color alone.

## Never

- Raw hex values or the raw per-theme tokens (`--ember-accent`) in product code.
- Two themes on one screen, or a theme re-tinted beyond the tweak budget.
- Blue-to-purple gradients, emoji as icons, cards with a colored left border, decorative blobs outside the canvas, glow on anything but the hero or primary.
- More than one primary button, hero or highlighted bar per view.
- Status shown by color alone, gray text below 4.5:1, focus rings removed.
- Animating everything. Motion marks a press, a first view or a change, nothing else.

## Reference

- Docs: https://enma.manishmandal.com (every page in every theme)
- Everything in one file: https://enma.manishmandal.com/enma.md

---
name: enma-frontend
description: Set up and build frontends with Enma, Manish Mandal's design system, on any platform (Next.js, Vite, React Native and Expo, Chrome extensions, VS Code webviews, plain HTML and Claude artifacts, CLIs). Use when starting a project with Enma, wiring Enma into an existing app, building a screen end to end, or checking a screen against Enma's definition of done. Pair it with the enma-design skill for the visual rules.
---

# Enma frontend

The companion to `enma-design`: how to set Enma up, build screens in the right order and ship them to Enma's standard.

## 1. Set up the project

Write the UI decision at the top of the project's README or AGENTS.md first: `UI: Enma · <theme> · <mode> (home), toggle: no`.

| Platform                         | Setup                                                                                                                                                                |
| -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Next.js, Vite, any React web app | Install `enma`, `import 'enma/css'` and `import 'enma/fonts/<theme>'` once, wrap the app in `<EnmaRoot theme>` or set `data-enma` and `data-theme` on `<html>`       |
| React Native, Expo               | Install `enma` plus `react-native-reanimated` and `expo-haptics`, load the theme's `@expo-google-fonts/*`, wrap the app in `<EnmaProvider theme>` from `enma/native` |
| Chrome extension                 | `@enma/css` with local fonts; UI injected into pages goes inside a Shadow DOM root                                                                                   |
| VS Code webview                  | `@enma/css` plus `@enma/css/vscode.css`, `data-enma="graphite"` and `data-theme` from VS Code's body class                                                           |
| Plain HTML, Claude artifacts     | Inline `enma.css`, set the root attributes, use the class recipes                                                                                                    |
| CLI                              | No CSS: apply the rules (one accent, units, words with status, `NO_COLOR`)                                                                                           |

Exact code for each: [references/setup.md](references/setup.md). Starters with everything wired: `pnpm dlx tiged --mode=git manishMandal02/enma-design/starters/<react-vite|next|expo|chrome-extension|html> my-app` (`--mode=git` clones over SSH, which the private repo needs).

Install from npm with `pnpm add enma@npm:enma-design` (no token or registry setup), so imports read `enma/react`, `enma/css` and so on.

## 2. Build each screen in this order

1. Layout and navigation (`TabBar` on mobile, a sidebar or top bar on web).
2. The hero (`Card variant="hero"` with a `Stat`, or a display title).
3. Content from existing components (`ListGroup`, `Table`, `Card`, `Stat`, `Bars`, `LineChart`).
4. States: loading, empty, error and offline.
5. Only then custom UI, styled with `--e-*` roles or the Tailwind mapping (`enma/tailwind.css`), never raw values.

`className` and `style` on components are for layout only (margin, grid placement, width). Never restyle a component's colors, radius or type from outside; change the system instead.

## 3. States every screen needs

- **Loading:** skeletons shaped like the content (`--e-raised` blocks, slow shimmer, none under reduced motion), only after about 300ms. No full-screen spinners.
- **Empty:** an invitation: a title that names the space ("Log your first workout"), one line and the primary action.
- **Error:** what happened and what to do, in one sentence, with a retry. Keep the data already on screen.
- **Offline (mobile, extensions):** cached content marked as stale; queue writes.
- **Edges:** very long names; zero, one and many items; large numbers ("1,284,000").

## 4. Accessibility (WCAG 2.2 AA)

- Semantics first: `<button>` for actions, `<a>` for navigation, `<label>` for every input, one `h1`, landmarks.
- Every icon button has a label, images have `alt`, charts have a text summary (Enma's charts build one).
- Forms: visible labels, the right `type`, `inputmode` and `autocomplete`; errors tied to the field; focus moves to the first error on submit.
- Toasts use `role="status"` (errors `role="alert"`); nothing important lives only in a toast.
- 44px touch targets on mobile, nothing hover-only, usable at 200% zoom and 320px width.
- Respect `prefers-reduced-motion`. Never remove the focus ring.
- Test: `eslint-plugin-jsx-a11y`, axe (`@axe-core/playwright` or `jest-axe`), a keyboard pass and a screen reader pass.

## 5. Keyboard and shortcuts

Everything works with a keyboard, in visual order, with a visible focus ring. Escape closes the top overlay. Dialogs trap focus and return it to the trigger. Standard map: Cmd/Ctrl+K palette, `/` search, `?` shortcut sheet, `J`/`K` next and previous, `Enter` open, `C` create, `G` then a letter to go somewhere, Cmd/Ctrl+Enter submit. Single-letter shortcuts never fire in text fields and can be turned off. Details: [references/standards.md](references/standards.md).

## 6. Performance budgets

LCP under 2.5s, INP under 200ms, CLS under 0.1 (75th percentile). App shell under about 150 KB of JavaScript gzipped. Only the active theme's fonts, `woff2`, `font-display: swap`. Animate only `transform` and `opacity`. Virtualize lists over about 100 rows.

## 7. Definition of done

A screen ships when every line is true:

- [ ] Built from Enma components and `--e-*` tokens only, within the tweak budget.
- [ ] One hero, one accent spark, one primary action.
- [ ] Works in the theme's home mode, and in the other mode if the app has a toggle.
- [ ] Loading, empty, error and offline states exist.
- [ ] Fully usable with keyboard only, with a visible focus ring; shortcuts follow the standard map.
- [ ] No axe violations; screen reader names make sense; usable at 200% zoom and 320px width.
- [ ] Respects reduced motion; motion only on press, first view and change.
- [ ] Meets the performance targets on a mid-range phone and a throttled connection.
- [ ] Copy follows Enma's voice: sentence case, verbs first, no "successfully".