Illusion/sharper.ly
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
2c51c35fe8aba4b9ea1bdf8caed8d85dafa8f54d
sharper.ly/apps/web/app/styles/README.md
T
IllusionandClaude Opus 5 19fab4a783 Match the shipped styling to the Claude Design drafts 
An audit of all twelve draft files against the build turned up a set of
mismatches, most of them in the tier-2 token layer rather than in any one
component. Tier 1 is untouched throughout - only the meanings moved.

SHAPE. The drafts draw three corners, not five: 2px for a tag, thumbnail,
flag or checkbox, 4px for anything with a box, and fully round for a filter
chip or status pill. Nothing in any draft is 8px or 12px. --radius-card and
--radius-surface therefore come down to radius/sm, a --radius-chip is added
for the 2px tier, and --radius-control-lg - a quirk of the Figma Button
frame's ghost cells - is retired along with its four consumers.

ELEVATION. A shadow is a fraction of the ground it falls on, and the ramp
was tuned for a white page: on the drafts' near-black ground a 12-28% black
is invisible. Tier 1 gains the two deep steps the drafts actually draw
(--shadow-dark-lg/xl), and --elevation-card/-popover/-modal move into the
per-surface blocks so the dark surface can take them while the light one
keeps the soft ramp. A resting card now has no shadow at all - the drafts
separate with a hairline - and the black is spent on what floats.

CARDS. The hover was a white-24% hairline and a faint glow; the drafts turn
the hairline accent green, lift the card 6px and land a deep black under it.
The lift is pointer-only and is dropped under prefers-reduced-motion.

GHOST IS A TEXT LINK. The drafts never fill a ghost control - every
"All updates ->" is plain text that turns green while the label-to-arrow gap
opens. The tokens carry no fill in any state and the variant opts out of the
3px lift, which also retires the WCAG workaround the old Figma hover forced
(green label on a green fill, 1.40:1).

NAVIGATION. A nav label rests in text/secondary and brightens to primary;
the current section stays primary and is marked by the accent rule, not by
green text.

HERO STRIPE. The middle block was painted near-black against a comment
claiming the redesign had dropped white; the drafts paint it #F8F9FA. Back
to background/inverse, and to the drafts' 390 : 495 : 363 split.

styles/README.md is updated to match, including a contrast table that still
described --surface-raised as the retired #2e2e2c.

Not changed, because each is a decision rather than a defect: the drafts set
every eyebrow, tag and meta line in IBM Plex Mono at 10-11px with 1.2-1.4px
tracking (a third typeface, and no Arabic counterpart); draft headings are
weight 800, which needs a font file we do not have; and the EU badge
statement stays at --text-primary, since the visibility lockup is
contractual.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-09-20 11:14:15 +02:00

311 lines
15 KiB
Markdown
Raw Blame History

# SHARP-ER design tokens
Two tiers, so changing the brand is a one-line edit in one file.
```
app/app.css entry - imports tailwindcss then the three files below
app/styles/primitives.css TIER 1 raw values, no meaning (@theme)
app/styles/semantic.css TIER 2 roles that alias tier 1 (per surface)
app/styles/typography.css TIER 2 type roles, @font-face, EN/AR font switch
```
## The one rule
**Components may reference only tier-2 tokens.**
Never a raw hex, never a tier-1 primitive.
This binds `app/app.css` too. Its `@layer base` block styles the document, so
the body type is set from `--type-body-base-size` / `--type-body-base-leading`
(the semantic alias of the Body/Medium role, declared in `semantic.css`) rather
than from `--text-md` / `--leading-6` directly. Only `primitives.css`,
`semantic.css` and `typography.css` may name a tier-1 token.
```tsx
// yes
<button className="bg-[var(--interactive-primary-bg)] text-[var(--interactive-primary-fg)]" />
<button className="bg-interactive-primary text-text-on-accent rounded-control" />
<h2 className="heading-h2 text-[var(--text-primary)]" />
// no
<button className="bg-[#008764]" /> // raw hex
<button className="bg-[var(--color-green-600)]" /> // tier-1 primitive
<h2 className="text-[28px] leading-[36px]" /> // raw type
```
Grep for violations: `grep -rn "#[0-9a-fA-F]\{6\}\|--color-green\|--color-neutral\|--color-red" app/components app/routes`.
### Two ways to spend a tier-2 token
1. `bg-[var(--surface-page)]` - works for every token, always correct.
2. A Tailwind utility from the bridge at the bottom of `semantic.css`. The name
is always `<tailwind-prefix>-<token-name>`:
`--surface-page` -> `bg-surface-page`, `--text-primary` -> `text-text-primary`,
`--border-subtle` -> `border-border-subtle`, `--radius-card` -> `rounded-card`.
The bridge uses `@theme inline`, so these still re-resolve inside a surface.
Type roles are utilities: `display-sm`, `heading-h1`, `heading-h2`, `heading-h3`,
`body-lg`, `body-lg-bold`, `body-md`, `body-md-bold`, `body-sm`, `body-sm-bold`,
`label-md`. They set family, size, line-height, tracking and weight together, and
they compose with variants (`md:heading-h1`).
## Tier 1 - primitives (`primitives.css`)
A Tailwind 4 `@theme static` block. Raw ramps only, named by value:
`--color-green-600`, never `--color-accent`.
* colour - `white`, `black`, `transparent`, `neutral-50..900`, `green-50..900`,
`red-50..900`, plus alpha steps (`white-a12`, `black-a56`, `green-a24`, ...)
* type - `--font-en` / `--font-ar` / `--font-sans` / `--font-mono`,
`--text-xs..5xl`, `--leading-4..12`, `--tracking-tighter..wider`,
`--font-weight-regular..black`
* space `--spacing-2xs..5xl` - radius `--radius-none..full` -
border width `--border-width-sm..xl` - opacity `--opacity-0..100`
* shadow `--shadow-xs..xl` plus the dark-ground steps `--shadow-dark-lg|xl` -
duration `--duration-instant..slower` -
easing `--ease-standard | decelerate | accelerate | emphasized`
* z ladder `--z-0..70` - containers `--container-prose | content | wide`
The hexes taken verbatim from the published Figma variables are marked `[figma]`;
the rest of each ramp is derived from them (tints mix with white, shades multiply
toward black).
### Changing a brand colour
Edit the ramp in `primitives.css` and nothing else. To move the brand green:
```css
--color-green-600: #008764; /* brand -> every accent, primary button, link */
--color-green-700: #006b4f; /* hover */
--color-green-800: #00563f; /* active */
--color-green-400: #4daa93; /* disabled fill, accent text on dark */
```
Same for `--color-red-*` (danger) and `--color-neutral-800/900` (the dark
surface). No component file changes.
## Tier 2 - semantics (`semantic.css`)
Plain CSS custom properties whose value is always `var(--<primitive>)`. Families:
`--surface-*` `--text-*` `--border-*` `--interactive-<variant>-*` `--field-*`
`--focus-ring-*` `--overlay-*` `--radius-*` `--control-*` `--layout-*`
`--elevation-*` `--motion-*` `--layer-*` `--type-body-base-*`
Two families are worth knowing by heart, because both were retuned to the
Claude Design drafts rather than to the older Figma Button frame:
* **Shape.** The drafts draw three corners, not five. `--radius-chip` (2px) for
a tag, thumbnail, flag or checkbox; `--radius-control` / `--radius-card` /
`--radius-surface` (all 4px) for a button, field, menu, card or panel;
`--radius-pill` for a filter chip or status pill. Nothing in the drafts is
8px or 12px, which is why the old `--radius-control-lg` is gone. The tier-1
ramp still carries `--radius-md` / `--radius-lg` - only the meanings moved.
* **Elevation.** A shadow is a fraction of the ground it falls on, so
`--elevation-card`, `--elevation-popover` and `--elevation-modal` are
declared **per surface**. On the dark surface a resting card has no shadow at
all (the drafts separate with a hairline) and the deep black - tier 1's
`--shadow-dark-lg` / `--shadow-dark-xl`, the drafts' own
`0 20px 44px rgba(0,0,0,.5)` and `0 24px 48px rgba(0,0,0,.6)` - is spent on
what actually floats: a card under the pointer, the nav dropdown. The light
surface keeps the soft ramp. Only `--elevation-flat` and `--elevation-raised`
are surface-independent.
Interactive tokens are fully regular - for each of the five Figma button
variants (`primary`, `secondary`, `dark`, `danger`, `ghost`) there is
```
--interactive-<variant>-bg -bg-hover -bg-active -bg-disabled
--interactive-<variant>-fg -fg-hover -fg-disabled
--interactive-<variant>-border -border-hover -border-disabled
```
Figma renders the disabled state as the default fill at 40% opacity; that
opacity is available as `--control-opacity-disabled`, and the `-disabled`
tokens above give the equivalent opaque colour for cases where a translucent
button would show the page through it.
## Surfaces, not a global theme
The home page is dark by default (`#1d1d1b`), while the nav and footer also have
light variants, so the whole tier-2 palette is redefined per surface rather than
per theme. `:root` **is** the dark surface; any element can flip its own subtree:
```html
<html lang="en" dir="ltr"> <!-- dark, the default -->
<header data-surface="light"> <!-- light nav on a dark page -->
<main>...</main>
<footer data-surface="light"> <!-- light footer -->
</html>
```
`data-surface` also sets `color-scheme` and paints `background-color` /
`color` on itself, so a flipped section is complete without extra classes.
Because both surface blocks define the *same* token names, a component written
against `--text-primary` is automatically correct on either one - which is why
components must never reach past a role to a primitive.
Utility variants `surface-dark:` and `surface-light:` exist for the rare case a
utility (not a token) has to differ, and `rtl:` / `ltr:` for direction. Prefer
CSS logical properties (`ps-`, `pe-`, `ms-`, `me-`, `start-`, `end-`) so RTL
mirrors without either.
## Fonts
Family stacks live in `primitives.css`; `@font-face` and the language switch live
in `typography.css`. `<html lang="ar">` (or any `:lang(ar)` subtree) rebinds
`--font-heading` / `--font-body` / `--font-ui` to the Arabic stack and resets all
letter-spacing to normal, because Arabic is a joined script. Nothing else changes.
Files in `apps/web/public/fonts/`:
| file | family | weight | status |
| --- | --- | --- | --- |
| `Panton-Regular.woff2` | Panton | 400 | present |
| `Panton-Bold.woff2` | Panton | 700 | present |
| `Panton-SemiBold.woff2` | Panton | 500 | **not supplied** |
| `Montserrat-Arabic-Regular.woff2` | Montserrat Arabic | 400 | present |
| `Montserrat-Arabic-Medium.woff2` | Montserrat Arabic | 500-600 | present |
| `Montserrat-Arabic-Bold.woff2` | Montserrat Arabic | 700 | present |
> The communication guideline PDF names the Arabic face "Montaser Arabic". That
> is a **typo in the guideline** - the correct face is **Montserrat Arabic**,
> confirmed with the client on 2026-09-11. Do not add a "Montaser Arabic"
> family back to `--font-ar`.
One gap, handled without any code change when the file arrives:
* **Panton SemiBold.** `label-md` asks for weight 500 and, with no SemiBold face
declared, CSS font matching resolves it to Panton Regular. When the cut is
supplied, add one `@font-face` for `"Panton"` at `font-weight: 500 600` in
`typography.css`. Do not declare that face before the file exists - a face that
fails to load drops weight-500 text out of the family altogether.
Filenames are case-sensitive in production - match the table exactly.
## Known deviation from Figma
**Ghost is a text link, not a button.** The published Figma Ghost cell fills on
hover (`background/accent` behind a `base/turquoise-dark` label - 1.40:1, a
WCAG AA failure). The Claude Design drafts never fill a ghost control: every
"All updates ->" / "What we do ->" is plain text in `--text-primary` that turns
accent green under the pointer while the label-to-arrow gap opens from 8px to
12px. The drafts win, so the ghost tokens carry no fill in any state, the
variant opts out of the 3px lift in `Button.css`, and the old a11y workaround
is no longer needed.
## Contrast audit
WCAG 2.1 relative luminance, computed from the sRGB hexes in `primitives.css`.
Translucent surfaces are composited over their own `--surface-page` first.
AA needs **4.5:1** for body text, **3:1** for large text (>=24px, or >=18.66px
bold) and for non-text UI boundaries (1.4.11).
### Dark surface (`:root`, `[data-surface="dark"]`)
| text token | page `#1d1d1b` | raised `#141413` | sunken `#0b0b0a` | muted (white 8%) | accent-subtle (green 24%) | danger-subtle (red 24%) |
| --- | --- | --- | --- | --- | --- | --- |
| `--text-primary` neutral-50 | 16.02 | 17.49 | 18.68 | 12.71 | 12.40 | 12.86 |
| `--text-secondary` neutral-300 | 9.46 | 10.33 | 11.04 | 7.51 | 7.32 | 7.60 |
| `--text-tertiary` neutral-400 | 5.56 | 6.07 | 6.48 | 4.41 | 4.30 | 4.46 |
| `--text-accent` / `--text-link` green-400 | 6.02 | 6.57 | 7.02 | 4.78 | 4.66 | 4.83 |
| `--text-link-hover` green-300 | 8.56 | 9.35 | 9.99 | 6.80 | 6.63 | 6.87 |
| `--text-danger` red-400 | 5.39 | 5.89 | 6.29 | 4.28 | 4.17 | 4.33 |
| `--text-disabled` neutral-500 | 2.36 | 2.58 | 2.76 | 1.88 | 1.83 | 1.90 |
`--text-primary`, `--text-secondary` and `--text-link-hover` pass AA everywhere.
Everything below them is only cleared against `--surface-page` and
`--surface-sunken`, which is where the design actually uses them:
* `--surface-raised` is the drafts' `#141413`, DARKER than the page, so every
role gains contrast on it rather than losing it - the whole column clears AA.
* `--text-tertiary`, `--text-accent`, `--text-link` and `--text-danger` land
between 4.17 and 4.78 on the three translucent fills - AA for large text,
**not** for body text. Card bodies use `--text-secondary`; keep
tertiary/accent/danger body copy on an opaque surface, or raise it a step.
* `--text-disabled` is 2.36:1 by design. WCAG 1.4.3 exempts the label of a
disabled control, so this is deliberate and must not be repointed - it is
the only token allowed below 3:1.
### Light surface (`[data-surface="light"]`)
| text token | page/raised `#ffffff` | sunken `#f8f9fa` | muted `#e8e8e8` | accent-subtle `#dbeee9` | danger-subtle `#fae2e2` |
| --- | --- | --- | --- | --- | --- |
| `--text-primary` neutral-800 | 16.88 | 16.02 | 13.78 | 14.00 | 13.70 |
| `--text-secondary` neutral-500 | 7.14 | 6.77 | 5.83 | 5.92 | 5.80 |
| `--text-tertiary` neutral-500 | 7.14 | 6.77 | 5.83 | 5.92 | 5.80 |
| `--text-link-hover` green-800 | 8.74 | 8.29 | 7.13 | 7.25 | 7.09 |
| `--text-link` green-700 | 6.53 | 6.19 | 5.33 | 5.42 | 5.30 |
| `--text-danger` red-600 | 5.78 | 5.48 | 4.72 | 4.79 | 4.69 |
| `--text-accent` green-600 | 4.52 | 4.28 | 3.69 | 3.75 | 3.67 |
| `--text-disabled` neutral-400 | 3.04 | 2.88 | 2.48 | 2.52 | 2.47 |
* `--text-tertiary` used to point at neutral-400 (`#949492`), 3.04:1 on white -
a body-text failure. It now points at neutral-500, the same primitive as
`--text-secondary`; the two are kept as separate roles so the ramp can be
re-split when a compliant mid-grey is added. `#949492` survives on
`--text-disabled` only, where 1.4.3 exempts it.
* `--text-accent` (the brand green) is 4.52:1 on white and passes, but only just
- it drops to 3.67-3.75 on the muted and subtle fills, which is large-text
only. Use `--text-link` (green-700, 5.30+ everywhere) for accent body copy on
a tinted light panel.
### Foreground on a filled background
| pair | ratio |
| --- | --- |
| `--text-on-accent` white on `--surface-accent` green-600 | 4.52 |
| `--text-on-accent` white on `--surface-danger` red-500 | 4.59 |
| dark `--text-on-inverse` neutral-800 on `--surface-inverse` white | 16.88 |
| light `--text-on-inverse` neutral-50 on `--surface-inverse` neutral-900 | 18.68 |
### Interactive variants (identical on both surfaces unless noted)
| pair | ratio |
| --- | --- |
| primary `fg` white / `bg` green-600 | 4.52 |
| primary `fg-hover` white / `bg-hover` green-700 | 6.53 |
| primary white / `bg-active` green-800 | 8.74 |
| **primary `fg-disabled` white / `bg-disabled` green-400** | **2.80** |
| danger `fg` white / `bg` red-500 | 4.59 |
| danger white / `bg-hover` red-600 | 5.78 |
| danger white / `bg-active` red-700 | 7.32 |
| **danger `fg-disabled` white / `bg-disabled` red-300** | **2.11** |
| dark `fg` white / `bg` neutral-900 | 19.69 |
| dark white / `bg-hover` black | 21.00 |
| dark `fg-disabled` neutral-300 / `bg-disabled` neutral-600 (dark surface) | 5.39 |
| dark `fg-disabled` neutral-200 / `bg-disabled` neutral-500 (light surface) | 4.91 |
| ghost `fg` neutral-50 / dark page (no fill in any state) | 16.02 |
| ghost `fg-hover` green-400 / dark page | 6.02 |
| ghost `fg` neutral-800 / light page | 16.88 |
| ghost `fg-hover` green-700 / light page | 6.53 |
| **ghost `fg-disabled` neutral-500 / dark page** | **2.36** |
| **ghost `fg-disabled` neutral-400 / light page** | **3.04** |
| secondary `fg` neutral-50 / dark page | 16.02 |
| secondary `fg` neutral-800 / light page | 16.88 |
| **secondary `fg-disabled` neutral-500 / dark page** | **2.36** |
| **secondary `fg-disabled` neutral-400 / light page** | **3.04** |
The bolded disabled rows are the WCAG 1.4.3 exemption again - a disabled
control has no contrast minimum. Every enabled pair clears 4.5:1.
### Fields and boundaries
| pair | dark | light |
| --- | --- | --- |
| `--field-fg` on `--field-bg` | 12.71 | 16.88 |
| `--field-placeholder` on `--field-bg` | 4.41 | 3.04 |
| `--field-border-focus` / `--focus-ring-color` against the page | 6.02 | 4.52 |
| `--field-border` against the page | 2.20 | 1.46 |
| `--border-subtle` against the page | 1.44 | 1.23 |
Two things to know here:
* **`--field-placeholder` is 3.04:1 on the light surface.** A placeholder is not
a label and never carries information in this codebase (`Input` always renders
a real `<label>`), so it is treated like disabled text. Do not promote it to
hint text.
* **`--field-border` and `--border-subtle` are below the 3:1 that 1.4.11 asks of
a control boundary.** They are decorative hairlines: the field's *state* is
carried by `--field-border-focus` (6.02 / 4.52), by the focus ring, and by the
`--text-danger` error message, none of which rely on the resting border. A
field whose only affordance is the resting border would fail.
Reference in New Issue View Git Blame Copy Permalink