Lovable

Make your Lovable app look like your brand

Glyph gives Lovable a brand to build with: tokens for light and dark, your fonts and logo, and a design system it can follow. Then audit the deployed app to see what drifted.

The exact files Glyph writes, shown here for an example brand called Ledgerly. Yours use your own colors, fonts and logo.

# Ledgerly design system

## Before you build
- Import `brand/tokens.css` once in the root layout. Use only its variables (`var(--brand-primary)`, or Tailwind `bg-brand-primary`, `text-brand-text`, `font-display`) for color and type. Never hardcode another color.
- Load "Manrope" (display, weight 500) and "Inter" (body, weight 400) through the stack's font loader, such as next/font/google.
- The logo is `public/logo.svg`. Use it in the navigation and footer as an image with the brand name as its alt text. Keep its proportions and colors, leave clear space around it, and never swap it for an icon.

## How to use this system
1. Read this section and follow the priority order when rules conflict.
2. Before building a component, check whether the project already has it; build new ones only from these tokens.
3. Use only the tokens below. If one you need is missing, stop and say so rather than inventing it.

## Priority order
When rules conflict, the earlier one wins:
1. Accessibility and keyboard behavior
2. Tokens, never raw values
3. Existing components, never rebuilt
4. Layout and spacing scale
5. Polish: motion, radius, details

## Tokens
| Token | Use for | Light | Dark | Contrast (light / dark) |
|-|-|-|-|-|
| `--ds-action-primary-bg` | the one primary action per view | `#0F766E` | `#1ee6d5` |  |
| `--ds-action-primary-fg` | text on the primary action | `#ffffff` | `#000000` | 5.5:1 / 13.3:1 |
| `--ds-text-default` | body text and headings | `#14181A` | `#f4f5f5` | 16.7:1 / 17.7:1 |
| `--ds-text-subtle` | secondary text, captions; the floor for readable text | `#5b6366` | `#778887` | 5.7:1 / 5.2:1 |
| `--ds-text-link` | links in running text | `#0f766e` | `#1ee6d5` | 5.1:1 / 12.3:1 |
| `--ds-surface-page` | the page | `#F7F7F5` | `#0c0e0d` |  |
| `--ds-surface-raised` | cards and panels | `#FFFFFF` | `#181b1b` |  |
| `--ds-surface-sunken` | wells for code and read-only values | `#ededeb` | `#191b1a` |  |
| `--ds-border-default` | dividers and control outlines | `#E3E5E4` | `#2b3130` |  |
| `--ds-focus-ring` | the keyboard focus outline | `#0f766e` | `#f7b546` |  |
| `--ds-status-success-fg` | success words and icons | `#16743e` | `#4bdd8a` | 5.4:1 / 11.1:1 |
| `--ds-status-warning-fg` | warning words and icons | `#805c19` | `#ddaa4b` | 5.7:1 / 9.2:1 |
| `--ds-status-danger-fg` | error words, destructive actions | `#b42e22` | `#df6358` | 5.8:1 / 5.6:1 |
| `--ds-status-info-fg` | neutral notices | `#2065a7` | `#4b96dd` | 5.6:1 / 6.2:1 |

## Type, space and radius
| Role | Font | Size | Weight | Line height |
|-|-|-|-|-|
| Display | Manrope | 40px | 500 | 1.15 |
| Heading 1 | Manrope | 32px | 500 | 1.15 |
| Heading 2 | Manrope | 28px | 500 | 1.2 |
| Body | Inter | 16px | 400 | 1.65 |
| Caption | Inter | 14px | 400 | 1.5 |

Spacing steps: 4, 8, 12, 16, 24, 32, 48, 64px. Control and card radius: 6px (`--ds-radius-md`); small marks `--ds-radius-sm`, large panels `--ds-radius-lg`.

## Global rules
- **ledgerly-tokens-only** MUST Use the --ds-* semantic tokens in components and the --brand-* tokens only for brand moments (logo, brand field, illustration); never a hex, rgb or arbitrary px. Because a raw value keeps its light-theme color in dark mode and drifts off the scale.
  - Correct: `<button className="bg-[var(--ds-action-primary-bg)] text-[var(--ds-action-primary-fg)]">`
  - Wrong: `<button className="bg-[#0F766E] text-white">`
- **ledgerly-base-not-in-components** NEVER Reference a shade-scale step (such as primary-500) directly in a component. Because base steps do not change with the color mode; only the semantic layer does.
- **ledgerly-components-first** MUST Reuse the project's existing components before writing new markup, and build any new one from these tokens. Because hand-built markup skips focus rings, keyboard handling and states, which people notice one at a time.
  - Correct: `<Button onClick={save}>Save changes</Button>`
  - Wrong: `<div onClick={save} className="cursor-pointer">Save</div>`
- **ledgerly-keyboard** MUST Keep every control keyboard-operable with an accessible name and a 2px --ds-focus-ring outline at 2px offset; never outline: none without a replacement. Because a keyboard user loses their place without the ring, and an unnamed icon button is announced as just "button".
- **ledgerly-sentence-case** MUST Write sentence case, plain labels and a verb with its object on actions. Because title case reads as proper nouns, and a bare OK or Submit does not say what the press will do.
  - Correct: `<Button>Create invoice</Button>`
  - Wrong: `<Button>Submit</Button>`
- **ledgerly-stop-when-missing** MUST Stop and say so when a token or component you need does not exist; do not invent one. Because an invented token resolves to nothing and renders unstyled.
- **ledgerly-smallest-change** SHOULD Make the smallest change that does the job; add no files or abstractions nobody asked for. Because every extra file is code someone has to review and keep.

## Color
- **ledgerly-one-primary** MUST Use --ds-action-primary-* for one action per view; every other action is secondary or a text button. Because the brand color marks the next step, and two of them leave no clear next step.
- **ledgerly-status-written** MUST Show status as a word with --ds-status-*-fg, plus its -bg fill or -border where needed; never color alone. Because color alone is lost in grayscale, in forced colors and to screen readers.
  - Correct: `<span className="text-[var(--ds-status-danger-fg)]">Payment failed</span>`
  - Wrong: `<span className="h-2 w-2 rounded-full bg-red-500" />`
- **ledgerly-warm-is-trouble** NEVER Use the warning or danger colors for anything but a warning or a failure. Because people scanning for trouble stop on every warm mark.
- **ledgerly-text-steps** MUST Set text in --ds-text-default or --ds-text-subtle; --ds-action-disabled-fg is for disabled controls only. Because subtle text is the readable floor at 4.5:1; anything lighter is not for words people must read.

## Typography
- **ledgerly-type-roles** MUST Use the type roles (display, heading, body, caption) from the brand fonts; never a one-off size or weight. Because a raw size skips the role's line height and tracking, so the line sits off its neighbours.
- **ledgerly-size-not-weight** SHOULD Make hierarchy with size and space, not by making text heavier. Because one bold heading outranks the page title and every label starts to shout.
- **ledgerly-mono-is-copyable** SHOULD Use a monospace face only for code, commands, IDs and keys; use tabular figures for numbers in tables. Because mono marks what a person copies, so a mono date looks like an ID.

## Buttons and forms
- **ledgerly-destructive-written** MUST Show a destructive action as a secondary button with --ds-status-danger-fg text and border, confirmed in a second step; not a red fill. Because a red fill outshouts the primary action, and the confirmation step stops a slip from becoming a loss.
- **ledgerly-pending-keeps-label** MUST Keep a button's width and label while it works: add a spinner beside the label and disable repeat presses. Because a label that swaps mid-press changes the width and the accessible name.
- **ledgerly-disabled-reason** SHOULD Say why a button is disabled in text beside it, not in a tooltip on it. Because a disabled button takes no hover on touch, so the tooltip never shows there.
- **ledgerly-no-button-in-link** NEVER Put a button inside a link or a link inside a button. Because it is invalid HTML, takes two tab stops and is announced twice.
- **ledgerly-label-above** MUST Give every input a visible 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.
- **ledgerly-errors-on-blur** MUST Check a field when it loses focus, then on each change while it is invalid; write the error as what to do, under the field, tied with aria-describedby. Because checking on the first keystroke flags a value before the person has finished typing it.
  - Correct: `Enter an email address like name@example.com.`
  - Wrong: `Invalid input!`

## Surfaces, elevation and motion
- **ledgerly-flat-surfaces** MUST Keep cards and sections flat: group with space first, then a --ds-surface-raised fill or a --ds-border-default line; never a card inside a card. Because boxes around everything flatten the page into equal parts.
- **ledgerly-shadow-overlays** MUST Give a shadow only to things that float: menus, popovers, dialogs and toasts use --ds-shadow-md or --ds-shadow-lg; a card at rest uses --ds-shadow-sm or none. Because a shadow says the thing floats, so a shadowed card makes people look for what it covers.
- **ledgerly-no-glass** NEVER Blur or fade an overlay; use the solid --ds-surface-overlay. Because the page shows through and pulls the overlay text under its contrast floor.
- **ledgerly-motion-on-change** MUST Animate only a change of state, with --ds-duration-* and --ds-ease-*; list the properties (color, background-color, opacity, transform), never transition: all. Because transition: all also tweens size and padding, which shifts layout on hover.
- **ledgerly-overlays-appear** NEVER Grow or scale a menu or dialog in, or tween the height of a collapsing panel; they appear and cut. Because a grow or height tween pulls the eye to the motion and reflows everything below it.

## Empty and error states
- **ledgerly-error-not-empty** MUST When a request fails, say it failed and why, with a retry; never show the empty state. Because "Nothing here yet" tells people the list is empty when the request failed.
- **ledgerly-empty-plain** SHOULD Write an empty state as a title naming the thing, one line on what to do and one action, placed where the first row would be; no illustration. Because a big centered picture pushes the cause and the action out of view.
- **ledgerly-no-cheer** NEVER Write "Oops!" or "Looks like…"; state the cause. Because "Oops" carries no cause, so nobody can tell a retry from a support ticket.
- **ledgerly-believable-data** SHOULD Fill examples with believable data: real-looking names, dates near today, amounts with cents; never Lorem ipsum or John Doe. Because placeholder data hides wrapping and length problems until launch.

## When to ask
Ask the person when a screen needs a credential, an endpoint, the target of a destructive action or real prices and claims you were not given. Decide layout, copy and components yourself from these rules, and say what you chose.

## How it looks
- Display type is tight (about -0.035em) with a line height of 1.04. Body text has a line height of 1.6.
- Primary is for the one main action and brand moments; accent is for emphasis. Check every text and background pair for 4.5:1 contrast.
- The brand field (`.brand-field`) is the signature surface. Use it once per page, for the hero visual or one feature panel, never as the whole background.
- Support dark mode with the `.dark` values.

## Voice
Plain, specific and short. Say what the product does for the customer.

Approved lines; use them as written where they fit:
- "Money decisions, with direction."

## Never
- No tracked capitals for labels or headings; use sentence case. Capitals read slower and make every label shout, so a real warning no longer stands out.
- No eyebrow label above a heading. The heading already names the section; a second label says less in a second voice.
- No decorative gradients, blobs or glows outside the brand field. Decoration competes with the one primary action.
- No glass: overlays and panels are solid surfaces. The page shows through and pulls text under its contrast floor.
- No colored bar on one edge of a card or row. An edge bar reads as a status stripe, so a normal item looks flagged.
- No status shown by a colored dot alone; write the word. Hue alone is lost to color-blind people, forced colors and screen readers.
- No pill shapes for static tags. A pill reads as a toggle, so people click a tag that does nothing.
- No row of equal stat cards. Equal boxes make every number equally loud, so the one that matters is lost.
- No icon in a tinted tile as decoration. It spends the brand color on ornament and names nothing a screen reader can read.
- No middle-dot separators between facts; give each fact its own element. Screen readers read each dot aloud, and the string wraps mid-fact on a phone.
- No "Learn more →" links; the link text names where it goes. A list of links read aloud becomes ten identical "learn mores".
- No looping decorative motion or content hidden until scrolled. Constant motion pulls the eye from what changed, and hidden content gets missed.
- No filler words such as "seamless", "effortless", "unlock", "elevate" or "supercharge". They say nothing a customer can check, and they mark the page as generated.
- No color outside the brand tokens, and no typeface other than Manrope and Inter. A model's default blue, violet and Inter make every product look the same.
- Never invent prices, customer counts, reviews, client logos or statistics.

## Skills to use with this brand
Install once per machine: `npx skills@latest add https://design.how`
- ui-review: run it on every screen you build before handing off, and fix what it ranks as broken.
- build-design-system and token-mapping: when the app grows, turn repeated styles into components and check that hardcoded values map onto the Ledgerly tokens.
- component-docs: document each shared component as you add it.
- make-motion: for a launch or feature video, build it with the Ledgerly tokens, fonts and the logo at public/logo.svg.
- Do not use make-logo or make-font to replace the Ledgerly logo or typefaces; they are already chosen.

## Motion picked for this brand
- `npx skills add https://design.how/vault/eclipse-grid`: a calm animated field behind the hero or an empty state. Settings: GROUND #0E1213, INK #F59E0B. Respect reduced motion, and keep the animation behind content, never under text it makes unreadable.
- `npx skills add https://design.how/vault/cloud-type`: a soft hero headline that drifts into focus. Settings: GROUND #F7F7F5; set GLYPHS to "Money decisions, w" and measure new boxes for it. Respect reduced motion, and keep the animation behind content, never under text it makes unreadable.
- `npx skills add https://design.how/vault/blur-reveal`: a sequence of brand lines for a launch video or a section intro. Settings: PANELS with your lines, bg #0F766E and fg #ffffff, then bg #F7F7F5 and fg #14181A. Respect reduced motion, and keep the animation behind content, never under text it makes unreadable.

## Before you hand off
Open each screen you changed at phone and desktop width and check it against every rule above. Fix what breaks a rule, then say which screens you checked.

Why it drifts

Why Lovable apps all look alike

  • The default look wins

    Without direction, Lovable reaches for the same gradient hero, the same violet and the same font. A brand with exact values gives it something else to reach for.

  • "Make it look better" reshuffles defaults

    Vague prompts produce a different arrangement of the same defaults. Concrete tokens and rules turn "better" into your colors and type.

  • Each prompt can undo the last

    A later prompt restyles a component and the brand drifts. Keeping DESIGN.md in the project gives every prompt the same reference.

  • Nobody checks the live app

    Drift shows up after deploy: an extra blue here, a fallback font there. The brand audit reads the live URL and lists what is off.

Setup

Set it up in Lovable

  1. 01

    Describe your Lovable app in Glyph, or paste its published lovable.app URL, and choose the identity it should wear.

  2. 02

    Add DESIGN.md to your Lovable project's knowledge, or paste the brand prompt from Glyph into the chat and ask Lovable to apply the system app-wide.

  3. 03

    Regenerate your key screens so they pick up the tokens.

  4. 04

    After you publish, run the free brand audit on your Lovable URL to catch colors and fonts that slipped through.

Questions

Common questions.

Will this change my whole Lovable app?
The brand prompt asks Lovable to apply the tokens everywhere (buttons, links, headings, backgrounds), so the change is app-wide, not one page.
Do I need to know design or code?
No. Describe your product or import your site, then paste what Glyph gives you into Lovable.
How do I check my deployed Lovable app?
Paste its URL into the brand audit. It reports how many colors and fonts the page uses, logo and favicon problems, dark mode readiness and contrast, with fixes.
Is it free?
Generating, previewing and the brand audit are free. The full export and the one-command install are part of the paid plans.