lime

# Lime Project override (Fairseat): the accent is blue (#356ed8), not acid lime, and the font is Inter, for words and numbers alike. Text on the accent is white in the light theme (--on-accent). Wherever these rules say lime, read the blue accent. The "No blue" line in the reject list does not apply to the accent. After installing a Lime component, run python3 scripts/retune-lime.py. Lime is a white page, warm-grey surfaces and near-black text with one acid lime on the main action, for consumer apps. Build with these components before writing markup. ## Steps 1. For a whole screen, start from a block under Blocks when one fits: install it, then swap its sample names, amounts and copy for the real ones. 2. Pick the components the screen needs from the index below. Fetch each one's page before using it: it has the props, variants and that component's rules. 3. Build only from those components and the tokens under Tokens, inside an element with the "lime" class. Import each from the path in the index; support pieces are under Imports. 4. Frame the screen with the Page shell. If a component is missing, build the stand-in under Coverage gaps; if none is listed, compose it from existing components and tokens and say what you built. Never invent a token. 5. Ask the person only when the screen needs an amount, a payee or an autonomy limit you were not given; never invent one. Decide everything else from these rules and say what you chose. 6. Porting an existing screen: swap one piece at a time for its component, keep the behavior and copy, and delete the old styles once nothing uses them. For a whole app, run migrate-design-system when it is installed. 7. Lint: install it once with `npx shadcn@latest add https://design.how/r/lime/lint.json`, then run `npx eslint -c lime.eslint.config.mjs .`. Each message names the fix. 8. Review before you finish: run the lint and fix every error, then render the screen at 390 and 1280 wide, check it against the global rules and the anti-slop list, fix the worst defect, and check again. Done when no MUST or NEVER is broken and no raw color, size or font is left. Run ui-review when it is installed. ## Priority order When rules conflict, the earlier item wins. 1. Accessibility and keyboard behavior 2. Tokens by role, never raw values 3. Existing components, never rebuilt 4. Spacing, radius and type scales 5. Polish: glow, motion, detail ## Global rules 1. lime-components-first MUST Use a Lime component before writing custom markup; fetch its page before you build. Because each one already carries the focus ring, states and touch size a hand-built copy forgets. - Correct: `import {Button} from '@/components/lime/ui/button'` 2. lime-scope MUST Wrap Lime UI in className="lime" with LimePortalProvider inside it, so overlays keep the tokens. Because a menu or dialog renders at the end of the body, outside the scope, and would lose every color. - Correct: `<div className="lime"><LimePortalProvider>{children}</LimePortalProvider></div>` 3. lime-tokens-only MUST Use only the token names Lime defines, such as --fg, --surface and --accent; never a hex value, arbitrary px or dark: variant. Because the dark theme and any retune change the roles, and a raw value stays behind. - Correct: `<p className="text-fg">` - Wrong: `<p className="text-[#0f0f0d]">` 4. lime-one-action MUST Use one lime primary action per view; every other action is solid, secondary, outline or ghost. Because the glowing lime is how the person finds the next step in a second. 5. lime-lime-scarce NEVER Fill a page, card or section with lime, or put white text on it; text on lime is --on-accent. Because white on lime is unreadable and a lime block drowns the one action. - Wrong: `<Card className="bg-accent text-white">Your goals</Card>` 6. lime-glow-scarce NEVER Add glow beyond primary and destructive buttons, the balance chip and one featured card. Because two glowing things compete and neither reads as the action. - Wrong: `<Card variant="glow">Recent activity</Card> // beside the upgrade card` 7. lime-money-sign MUST Format every amount with formatAmount or Amount, never by hand: formatAmount text in List and Table rows, the Amount pill for a sum beside a control or one that needs a tone. Because a hand-built string drops the minus, the separators or the tabular figures. - Correct: `import {Amount, formatAmount} from '@/components/lime/ui/amount'` - Wrong: `<span>${total}</span>` 8. lime-ask-before-money MUST When the assistant moves money, show an ApprovalRequest first and an ActionReceipt with Undo after; when the person pays, show a review step and then Payment done with Undo. Because money that moves without a check, or with no way back, is the one mistake people do not forgive. - Correct: `<ApprovalRequest title="Pay Maya for dinner" amount={-24} reason="Your half of Friday dinner"/>` 9. lime-field-label MUST Wrap every input in Field with a label above it; a placeholder is not a label. Because a placeholder disappears as soon as the person types and is not read as a name. - Correct: `<Field name="title"><FieldLabel>Goal name</FieldLabel><Input/></Field>` 10. lime-focus MUST Keep every control keyboard-operable with the 2px olive :focus-visible ring; never outline: none. Because keyboard and switch users lose their place without it. 11. lime-section-heading MUST Name a section with a real heading (an h2 at text-lg font-semibold in --fg) or not at all; never a small text-sm or text-xs label above the content. Because a small grey label above content is skipped by heading navigation and makes every section look the same. - Correct: `<h2 className="text-lg font-semibold">Recent activity</h2>` - Wrong: `<p className="text-sm font-medium text-fg-3">Recent activity</p>` 12. lime-sentence-case MUST Write sentence case and a verb with its object on actions; no emoji, no em dash, no title case. Because the copy then reads like a person talking, and every screen sounds the same. - Correct: `<Button>Send money</Button>` - Wrong: `<Button>OK</Button>` ## Page shell Every screen sits in this frame. - Root: `<div className="lime min-h-dvh bg-page text-fg">` with `LimePortalProvider` inside it - One task, such as send or pay: `<main className="mx-auto w-full max-w-md px-4 pt-4 pb-8 sm:px-6 sm:pt-8">` - Home, activity, settings: the same `main` at `max-w-2xl` - A Table on a wide screen: the same `main` at `max-w-5xl` - Header: `<header className="sticky top-0 z-10 flex h-14 items-center gap-2 bg-page">`: a ghost `size="icon"` Button with `aria-label="Back"`, then the h1; add `border-b border-line` once content scrolls under it - Page title: `<h1 className="text-xl leading-tight font-semibold tracking-tight sm:text-2xl">`, one per page - Section: `<section className="flex flex-col gap-3">` led by an h2 at `text-lg font-semibold`; sections sit `gap-8` apart - Form: Fields in `flex flex-col gap-4` at `max-w-md`; the submit Button last, `size="lg"` and `w-full` on a phone - Main action of a phone flow: `<div className="sticky bottom-0 bg-page pt-3 pb-4">` holding `<Button size="lg" className="w-full">`; add the safe-area inset under a home bar ## Anti-slop The habits of generated UI that Lime bans. Details: https://design.how/systems/lime/foundations/anti-slop.md - anti-slop-no-eyebrow NEVER Put a small label, a category or a number such as 01 above a title or a section. Because the heading already names the section, and the label only adds a second voice saying less. - Wrong: `<p className="text-xs font-medium text-fg-3">Overview</p><h2>Spending</h2>` - anti-slop-no-stat-cards NEVER Lay out a row of equal cards each holding one number; show one Balance, a List or a sentence. Because equal boxes make every number equally loud, so the one that matters is lost. - Wrong: `<Card>Income</Card><Card>Spent</Card><Card>Saved</Card>` - anti-slop-earn-surface MUST Group with space first; use a Card only around one thing the person acts on, and never put a Card in a Card. Because boxes around everything flatten the page into equal tiles and the eye has nowhere to start. - anti-slop-no-icon-tiles NEVER Put an icon in a tinted tile, or beside a heading or a stat as decoration; ListIcon in a List row is the one round mark. Because a decorative icon carries no meaning and pulls the eye from the words. - Wrong: `<span className="rounded-panel bg-accent-wash p-2"><Icon icon={Wallet}/></span>` - anti-slop-no-side-rail NEVER Mark a card, row or quote with a colored bar on one edge; use --accent-wash for a chosen row. Because the bar reads as a status nobody defined. - Wrong: `<div className="border-s-4 border-accent">` - anti-slop-no-decoration NEVER Add a gradient, blob, texture, grid or dot background, glass blur, or a glow beyond the sanctioned ones. Because decoration competes with the one glowing action, which is the only light Lime allows. - Wrong: `<div className="bg-gradient-to-br from-accent to-surface backdrop-blur">` - anti-slop-sticky-edge MUST Give a sticky header a --line bottom edge once content scrolls under it, and none at the top. Because without the edge, scrolled text slides under the title with nothing to say where the header ends. - anti-slop-icon-first-line MUST Align a leading icon to the first line of its text, not the middle of a block that wraps. Because a centered icon drifts away from the line it labels once the text runs to two lines. - anti-slop-no-small-prose NEVER Set a sentence the person must read, such as a fee or a limit, in text-xs or --fg-3; use text-sm in --fg or --fg-2. A FieldDescription hint is the exception. Because small grey text fails people reading in sunlight or with low vision, and a sentence is meant to be read. - Wrong: `<p className="text-xs text-fg-3">Transfers over $1,000 take one extra day to arrive.</p>` - anti-slop-peer-amounts MUST Set amounts that are peers, such as the rows of one list, at one size and weight. Because a bigger or bolder peer reads as more important when it is not. - anti-slop-no-caps NEVER Set text in capitals or spread its letters out; keep sentence case. Because capitals are slower to read and shout. - Wrong: `<span className="uppercase tracking-widest">Queued</span>` - anti-slop-no-hype NEVER Write instant, secure, effortless, seamless or invented urgency such as Only 2 hours left; say what happens and when. Because people trust an app that states the fact, and hype reads as a sales pitch over their money. - Wrong: `Instant, secure transfers. Act now!` - anti-slop-no-emoji NEVER Use emoji in copy, titles, buttons or as icons; use words and the Icon set. Because emoji render differently on every device and turn a money app into a chat thread. - Wrong: `<Button>Send 💸</Button>` - anti-slop-no-fake-data SHOULD Fill examples with believable data: real-looking names, amounts with cents, dates near today; never Lorem ipsum, John Doe or $1,234.56. Because placeholder data hides truncation and alignment problems that real data shows at once. - anti-slop-no-stream-effects NEVER Blink a cursor, sweep a shimmer or fade in each word of a streamed answer; let the text arrive as it is. Because the effect slows reading and makes the layout jitter while the person tries to read. - Wrong: `<span className="animate-pulse">▍</span>` - anti-slop-no-scroll-reveal NEVER Fade, slide or scale content in as it scrolls into view. Because content that hides until scrolled is missed, and motion that answers nothing is decoration. - Wrong: `<motion.section whileInView={{opacity: 1, y: 0}}>` - anti-slop-dialog-controlled MUST Open a Dialog, Sheet or AlertDialog with open and onOpenChange; never mount it only while open. Because a dialog that unmounts skips its exit motion and loses the trigger it returns focus to. - anti-slop-keep-one-glow MUST Keep one glowing primary action on every view while removing the rest; never flatten a screen to grey. Because Lime without its one lime action is a grey page with nowhere to go next. ## Reject list - No blue, no second brand hue, no gradient behind content, no colored shadows. - No second icon set, no weight 700, no letter-spaced capitals. - No transition: all, no looping animation except the spinner. ## Coverage gaps Not in the system yet, and what to build meanwhile. - Bottom navigation: a `<nav aria-label="Main">` fixed to the bottom on `bg-page` with `border-t border-line`, 3 to 5 links each an Icon at 20 over a `text-xs` label, at least 56px tall; the current one has `aria-current="page"` in `--fg`, the rest `--fg-3`. - Date picker: an Input with `type="date"` inside a Field. - Charts beyond a sparkline: the Insight sparkline, or the figures in a List; no chart library. ## Imports - `import {ListItemMenu} from '@/components/lime/ui/list-item-menu'`: A row's other actions behind a more button, for ListItem's menu. - `import {Collapsible, CollapsibleTrigger, CollapsibleContent} from '@/components/lime/ui/collapsible'`: One section that opens and closes, the base of the Why? in Approval request. - `import {cn, mergeClass} from '@/lib/lime/utils'`: cn, which merges class names and knows Lime's radius and shadow names, and mergeClass, which keeps Lime's classes when className is a function of state. - `import {Icon} from '@/components/lime/icon'`: The one import point for Carbon icons. - `import {LimePortalProvider, useLimePortal} from '@/lib/lime/portal'`: Puts overlays inside the .lime scope so they keep its tokens. - `import {useFocusWhenReplaced} from '@/lib/lime/use-focus-when-replaced'`: Moves focus to an outcome when the buttons that had it are replaced, so a keyboard user is not dropped to the top. - `import {popupClass, itemClass, groupLabelClass, separatorClass} from '@/lib/lime/popup'`: The panel, item and separator classes every floating list shares. ## Icons Import a glyph beside Icon from the path under Imports and pass it in: `<Icon icon={Add} size={16}/>`. These are all the names; another needs adding to that file first. Add, ArrowDown, ArrowRight, ArrowUp, Attachment, Checkmark, CheckmarkFilled, ChevronDown, ChevronRight, ChevronSort, ChevronUp, Close, Copy, ErrorFilled, Image, Information, Menu, Play, Receipt, Renew, Search, Send, Subtract, Time, Upload, Wallet, PiggyBank, Warning, WarningFilled, ChevronLeft, ArrowLeft, Pause, OverflowMenuHorizontal, Folder, Star, Plus, Delete, Cafe, ShoppingBag, Notification, Locked, Undo, Edit, CircleDash ## Tokens The closed list. Colors are utilities named after the role (bg-surface, text-fg-2, border-line); sizes read the scale (text-sm, rounded-panel, shadow-menu, h-(--control-lg), duration-(--dur-fast)). - Surfaces: --page, --surface, --surface-2, --surface-3, --raised, --field, --scrim - Text: --fg, --fg-2, --fg-3, --fg-disabled, --fg-inverse, --on-accent, --glow-accent-fg - Lines: --line, --line-strong, --control - Solid ink: --ink, --ink-hover, --ink-active - Accent: --accent, --accent-hover, --accent-active, --accent-wash, --accent-line, --ring - Status: --success, --success-tint, --success-text, --warn, --warn-tint, --warn-text, --danger, --danger-hover, --danger-tint, --on-danger, --danger-text - Elevation: --shadow-ink, --shadow-card, --shadow-menu, --shadow-overlay, --thumb, --switch-on, --switch-on-thumb, --shadow-thumb - Glow: 37 tokens read only through their classes and components; never by name. - Type: --font-sans, --font-mono, --text-xs, --text-sm, --text-base, --text-lg, --text-xl, --text-2xl, --text-3xl, --leading-tight, --leading-snug, --leading-normal, --tracking-tight, --weight-normal, --weight-medium, --weight-semibold - Size: --control-sm, --control-md, --control-lg - Radius: --radius-sm, --radius-md, --radius-field, --radius-panel, --radius-sheet, --radius-control - Motion: --dur-instant, --dur-fast, --dur-base, --dur-slow, --dur-spin, --ease-out, --ease-in, --scale-enter, --scale-press - Layers: --z-dialog, --z-popover, --z-toast - Layout: --overlay-sm, --overlay, --overlay-lg, --popover, --sheet, --popup-max, --focus-offset, --line-focus, --scrollbar-thumb ## Components ### Actions - [Button](https://design.how/systems/lime/components/button.md): Starts an action, such as Send money. The lime primary is the one glowing action on a screen. `import {Button, Spinner, buttonVariants} from '@/components/lime/ui/button'` - [Copy button](https://design.how/systems/lime/components/copy-button.md): Copies a value, such as a payment link, and confirms with a check. `import {CopyButton} from '@/components/lime/ui/copy-button'` ### Inputs - [Input](https://design.how/systems/lime/components/input.md): One line of text, such as a merchant name or a search. `import {Input, fieldControl} from '@/components/lime/ui/input'` - [Textarea](https://design.how/systems/lime/components/textarea.md): Several lines of text, such as a note on a payment. `import {Textarea} from '@/components/lime/ui/textarea'` - [Field](https://design.how/systems/lime/components/field.md): A label, a control, a hint and an error, wired together. `import {Field, FieldLabel, FieldDescription, FieldError} from '@/components/lime/ui/field'` - [Select](https://design.how/systems/lime/components/select.md): One choice from a list, such as an account or a category. `import {Select, SelectGroup, SelectLabel, SelectTrigger, SelectContent, SelectItem, triggerVariants} from '@/components/lime/ui/select'`