{"name":"aliabbas.net design tokens","description":"Read from the CSS and the code of the site. Use the Tailwind names in components. Follow the rules.","page":"https://aliabbas.net/design","sources":{"css":"https://github.com/alivault/aliabbas.net/blob/master/src/styles/globals.css","motion":"https://github.com/alivault/aliabbas.net/blob/master/src/lib/design/motion.ts","titles":"https://github.com/alivault/aliabbas.net/blob/master/src/components/Title.tsx","rules":"https://github.com/alivault/aliabbas.net/blob/master/src/lib/design/rules.ts","agents":"https://github.com/alivault/aliabbas.net/blob/master/AGENTS.md"},"colorSchemes":{"light":"Default.","dark":"From prefers-color-scheme: dark. There is no manual switch."},"color":{"background":{"group":"Surface","use":"The page.","light":"oklch(0.955 0.009 94)","dark":"oklch(0.121 0.0039 245.5)","tailwind":"bg-background"},"foreground":{"group":"Text","use":"All text. Lower its opacity for less important text.","light":"oklch(0.155 0.006 85)","dark":"oklch(0.98 0.006 94)","tailwind":"text-foreground"},"fg-secondary":{"group":"Text","use":"Supporting text next to primary text. APCA Lc 75 or more.","light":"oklch(0.36 0.008 85)","dark":"oklch(0.85 0.009 94)","tailwind":"text-fg-secondary"},"fg-muted":{"group":"Text","use":"Descriptions, metadata and hints. APCA Lc 60 or more.","light":"oklch(0.46 0.008 85)","dark":"oklch(0.77 0.008 94)","tailwind":"text-fg-muted"},"fg-faint":{"group":"Text","use":"Disabled text and decoration only.","light":"oklch(0.62 0.008 85)","dark":"oklch(0.59 0.007 94)","tailwind":"text-fg-faint"},"card":{"group":"Surface","use":"Cards and panels that sit on the page.","light":"oklch(0.98 0.005 94)","dark":"oklch(0.165 0.004 245.5)","tailwind":"bg-card"},"card-foreground":{"group":"Text","use":"Text on a card.","light":"oklch(0.155 0.006 85)","dark":"var(--foreground)","tailwind":"text-card-foreground"},"popover":{"group":"Surface","use":"Hover cards, menus and drawers.","light":"oklch(0.98 0.005 94)","dark":"oklch(0.165 0.004 245.5)","tailwind":"bg-popover"},"popover-foreground":{"group":"Text","use":"Text on a popover.","light":"oklch(0.155 0.006 85)","dark":"var(--foreground)","tailwind":"text-popover-foreground"},"primary":{"group":"Action","use":"The main button of a view.","light":"oklch(0.155 0.006 85)","dark":"var(--foreground)","tailwind":"bg-primary"},"primary-foreground":{"group":"Action","use":"Text on a primary fill.","light":"oklch(0.97 0.01 94)","dark":"var(--background)","tailwind":"text-primary-foreground"},"secondary":{"group":"Surface","use":"Quiet filled controls.","light":"oklch(0.91 0.012 94)","dark":"oklch(0.21 0.005 245.5)","tailwind":"bg-secondary"},"secondary-foreground":{"group":"Text","use":"Text on a secondary fill.","light":"oklch(0.155 0.006 85)","dark":"var(--foreground)","tailwind":"text-secondary-foreground"},"muted":{"group":"Surface","use":"Wells and hover fills.","light":"oklch(0.91 0.012 94)","dark":"oklch(0.21 0.005 245.5)","tailwind":"bg-muted"},"muted-foreground":{"group":"Text","use":"Text on a muted fill.","light":"var(--fg-muted)","dark":"var(--fg-muted)","tailwind":"text-muted-foreground"},"accent":{"group":"Action","use":"Hover fill of menu items.","light":"color-mix(in oklab, var(--foreground) 10%, transparent)","dark":"color-mix(in oklab, var(--foreground) 10%, transparent)","tailwind":"bg-accent"},"accent-foreground":{"group":"Action","use":"Text on an accent fill.","light":"var(--foreground)","dark":"var(--foreground)","tailwind":"text-accent-foreground"},"destructive":{"group":"Status","use":"Errors and actions that delete.","light":"oklch(0.58 0.22 27)","dark":"oklch(0.79 0.12 27)","tailwind":"bg-destructive"},"verified":{"group":"Status","use":"The claim checker: verified.","light":"oklch(0.52 0.12 152)","dark":"oklch(0.76 0.13 152)","tailwind":"bg-verified"},"partial":{"group":"Status","use":"The claim checker: partly verified.","light":"oklch(0.58 0.13 70)","dark":"oklch(0.8 0.13 80)","tailwind":"bg-partial"},"contradicted":{"group":"Status","use":"The claim checker: contradicted.","light":"oklch(0.55 0.2 27)","dark":"oklch(0.79 0.12 25)","tailwind":"bg-contradicted"},"border":{"group":"Line","use":"Dividers and card edges.","light":"oklch(0.82 0.012 94)","dark":"oklch(0.28 0.006 245.5)","tailwind":"border-border"},"input":{"group":"Line","use":"Edges of fields.","light":"oklch(0.82 0.012 94)","dark":"oklch(0.28 0.006 245.5)","tailwind":"border-input"},"ring":{"group":"Action","use":"The focus ring. Every control shows it.","light":"color-mix(in oklab, var(--foreground) 50%, transparent)","dark":"color-mix(in oklab, var(--foreground) 50%, transparent)","tailwind":"bg-ring"},"brand":{"group":"Action","use":"A light orange of the HUD, light enough for text: selection, the active citation and the active states of the lab. Not for titles.","light":"oklch(0.48 0.085 216.4)","dark":"oklch(0.78 0.14 50)","tailwind":"bg-brand"},"brand-foreground":{"group":"Action","use":"Text on a brand fill.","light":"var(--background)","dark":"var(--background)","tailwind":"text-brand-foreground"},"chrome":{"group":"Action","use":"The dark base of the liquid metal on a primary button on hover.","light":"oklch(0.12 0.005 260)","dark":"oklch(0.12 0.005 260)","tailwind":"bg-chrome"},"chrome-foreground":{"group":"Action","use":"The label on the liquid metal. APCA Lc 90 or more on chrome.","light":"oklch(0.99 0 0)","dark":"oklch(0.99 0 0)","tailwind":"text-chrome-foreground"},"hud":{"group":"Action","use":"The HUD of the world, the outline on the ground and the edge of a sheet under the pointer.","light":"oklch(0.6 0.19 37)","dark":"oklch(0.6 0.19 37)","tailwind":"bg-hud"},"sky-warm":{"group":"Surface","use":"The sky of the world, on the side of the sun.","light":"oklch(0.66 0.1 60)","dark":"oklch(0.66 0.1 60)","tailwind":"bg-sky-warm"},"sky-cool":{"group":"Surface","use":"The sky of the world, away from the sun.","light":"oklch(0.45 0.025 55)","dark":"oklch(0.45 0.025 55)","tailwind":"bg-sky-cool"},"sky-haze":{"group":"Surface","use":"The dark haze at the horizon of the world.","light":"oklch(0.24 0.02 55)","dark":"oklch(0.24 0.02 55)","tailwind":"bg-sky-haze"},"ground":{"group":"Surface","use":"The ground of the world, before the 3D scene loads.","light":"oklch(0.2 0.003 60)","dark":"oklch(0.2 0.003 60)","tailwind":"bg-ground"}},"text":{"fonts":{"hud":{"family":"Michroma","use":"The HUD and the readers: titles, labels, lists and links, in capitals spaced 0.42em."},"sans":{"family":"DM Sans Variable","use":"Long text in sentence case, and all text of the old page layout."},"mono":{"family":"JetBrains Mono","use":"Code, file paths and ids only. Never for labels."}},"minimumSize":"12px","tones":[{"name":"Primary","className":"text-foreground","use":"Headings and body text."},{"name":"Secondary","className":"text-fg-secondary","use":"Supporting text next to primary text."},{"name":"Muted","className":"text-fg-muted","use":"Descriptions, metadata and hints."},{"name":"Faint","className":"text-fg-faint","use":"Disabled text and decoration. Never for text that people must read."}],"titles":[{"variant":"page","role":"Page title (h1)","size":"36–48px","lineHeight":1},{"variant":"section","role":"Section title","size":"32–56px","lineHeight":1.15},{"variant":"card","role":"Card and project title","size":"24–32px","lineHeight":1.2},{"variant":"subsection","role":"Subsection title","size":"20–24px","lineHeight":1.3},{"variant":"detail","role":"Detail title","size":"18px","lineHeight":1.4}],"body":[{"className":"text-lg","size":"18px","lineHeight":"32px","use":"Lead paragraphs."},{"className":"text-base","size":"16px","lineHeight":"28px","use":"Body text."},{"className":"text-sm","size":"14px","lineHeight":"24px","use":"Controls, metadata and hints."},{"className":"text-xs","size":"12px","lineHeight":"20px","use":"Short labels, such as the section headings of the index. The smallest size."}]},"layout":{"breakpoints":{"sm":"40rem","lg":"64rem"},"tokens":[{"name":"header-height","use":"The fixed site header. Offsets under it use it (h-header, top-header).","base":"60px","sm":"60px","lg":"60px"},{"name":"section-padding","use":"Space above and below a page section.","base":"3rem","sm":"4rem","lg":"5rem"},{"name":"section-content-gap","use":"Space between a section title and its content.","base":"2rem","sm":"2.5rem","lg":"3rem"},{"name":"radius","use":"Corner radius of controls. Cards use radius + 4px, pills use full.","base":"0.5rem"}]},"motion":{"springs":{"layout":{"type":"spring","stiffness":380,"damping":36},"settle":{"type":"spring","stiffness":420,"damping":34},"pop":{"type":"spring","stiffness":540,"damping":27},"bloom":{"type":"spring","stiffness":220,"damping":18},"hover":{"type":"spring","stiffness":320,"damping":18}},"easeOut":[0.22,1,0.36,1],"easeIn":[0.64,0,0.78,0],"durations":{"enter":0.28,"exit":0.2,"page":0.55,"reveal":0.7,"showcase":1.1}},"rules":[{"id":"tokens-only","rule":"Use the color tokens (bg-background, text-fg-muted, border-border, text-brand). Do not write a color value in a component.","why":"One edit to a token then changes the whole site, and the colors stay in one scheme."},{"id":"text-size","rule":"No text under 12px, and no capitals made with CSS. Use text-xs (12px) as the smallest size, for short labels only; text-sm (14px) for controls and hints. The one exception to the capitals is the HUD of the world (data-hud): spaced capitals in font-hud, at 12px, because the face is wide. Its fields stay at 14px.","why":"Small capital labels are hard to read and add noise without meaning.","checkedBy":"e2e/pages.spec.ts"},{"id":"no-eyebrows","rule":"Do not put a small label above a heading. Put the meaning in the heading, or number the heading.","why":"A label above a heading repeats it, and screen readers read it as a separate line."},{"id":"mono-for-code","rule":"Use the mono font only for code, file paths and ids, at 14px or more.","why":"Mono marks text that a reader can copy into a terminal or an editor."},{"id":"titles","rule":"In a reader, make headings with ReaderTitle and ReaderSection (src/components/reader/Reader.tsx). In the old page layout, use Title, PageHeading or SectionHeading. Use className for layout only, not for size, weight or color. A title has one color: do not give some of its words or its number another shade.","why":"One scale for each layout. To change a size, change the component. A second shade in a title makes one title read as two."},{"id":"text-tones","rule":"Show less important text with text-fg-secondary or text-fg-muted. Do not lower the opacity of text-foreground. Use text-fg-faint only for decoration and disabled text.","why":"One opacity looks much dimmer on a dark background. Each tone has its own light and dark value, tested for APCA contrast in both schemes.","checkedBy":"src/lib/design/tokens.test.ts"},{"id":"color-not-alone","rule":"Never show a state with color alone. Add an icon and a text label.","why":"WCAG 1.4.1. The claim checker grades each have an icon, a label and a color."},{"id":"focus","rule":"Every control shows focus: the focus ring, or the fill of hud-fill. When an overlay closes, focus goes back to the control that opened it.","why":"Keyboard users must always know where they are.","checkedBy":"e2e/lab.spec.ts"},{"id":"states","rule":"A view that waits for the network has these states: idle, pending, streaming, complete, stopped and failed. Esc stops it, and the text that arrived stays.","why":"A stream can be slow, stop or fail at any point. Each case needs a clear screen.","checkedBy":"e2e/chat.spec.ts, e2e/check.spec.ts, e2e/lab.spec.ts"},{"id":"stale-events","rule":"Every stream event carries the attempt it belongs to. A reducer ignores events from an attempt that is not active.","why":"A stopped answer must not write into a new one.","checkedBy":"src/lib/chat/chat-machine.test.ts"},{"id":"motion-tokens","rule":"Animate with a spring, ease and duration from src/lib/design/motion.ts. Do not write new values in a component.","why":"The same kind of change then moves the same way on every page."},{"id":"hud-controls","rule":"A link or button in the HUD style uses the hud-fill utility: the HUD color fills it from the bottom on hover and on keyboard focus, and the label turns dark. Do not add another hover style to it.","why":"Every control in the world answers the same way, so a visitor learns it once."},{"id":"one-movement","rule":"In the world, the zoom of the camera to an icon is the only movement into a page. Text fades in, one line after the other, and does not slide.","why":"Two movements at once fight for the eye. The zoom already says where the visitor goes."},{"id":"reduced-motion","rule":"Respect reduced motion. Motion does this through MotionConfig at the root. CSS animations need a prefers-reduced-motion block.","why":"Large movement can make some people feel sick."},{"id":"targets","rule":"Make click and touch targets at least 24 by 24px. Buttons are 32px high.","why":"WCAG 2.5.8. Small targets are hard to hit on a phone."},{"id":"buttons","rule":"Buttons have four variants (primary, secondary, ghost, destructive) and four sizes (md, lg, icon, icon-lg), all round. Use at most one primary button in a view or group, with secondary next to it. Use destructive only to delete. A link that looks like a button is a ButtonLink or a ButtonAnchor, never a Button with a link in render.","why":"Few buttons that look the same everywhere make the site read as one product. Button with a link in render gives the link role=\"button\".","checkedBy":"src/components/ui/button.test.ts"},{"id":"dividers","rule":"Separate sections, and a heading from its content, with space (py-section, mb-section, pb-section-content), not with a line. Use a line only between the rows of a list or a table: put divide-y on the list, so there is no line above the first row or below the last. Lines use the default border color.","why":"A line at every edge makes every edge equal, so the page reads as a stack of boxes. Space groups content, and a line then means \"more of the same\"."},{"id":"components","rule":"Build on the shadcn/ui base-nova components in src/components/ui, on Base UI. Merge classes with cn from the cn package. Use Lucide icons.","why":"The primitives handle focus, keyboard and ARIA. Do not rebuild them."}]}