Align the site with the LeanCode palette, from one source

[claude]

Summary

Brings advanced-forms.leancode.co in line with the LeanCode design system (the LNCD handoff from Claude Design) and makes the palette a single source of truth across the whole site — the follow-up to leancodepl/ciach#47.

Why one source. The colors lived in nine places across four languages: landing/web/landing.css (light + dark), docs_app/app/global.css (the same --af-* set again, plus a third copy as literal hex in the Fumadocs @theme blocks), both OG routes (TS constants), components/logo.tsx, island_frame.dart (the accent inside the live Flutter demos), and four SVGs (app/icon.svg, public/logo-*.svg, landing-icon.svg). They had drifted: three different yellows (#edff2f, #f9ff07, #f6ff6b), a #050505 ground, blue-tinted grays.

The source. docs_app/palette.json names the design system's swatches (black, white, ctaYellow #f0ff00, bodyGray, mutedGray, surface/surface2, error, success, plus the site's own tints for the light theme) and the light/dark --af-* themes built from them, each token a swatch or a swatch at an alpha.

The generator. npm run palette:generate (scripts/palette.mjs) writes every consumer's copy, all committed:

• app/af-tokens.css and landing/web/af-tokens.css — the tokens as CSS variables (global.css imports one; the landing links the other before landing.css, and landing.mjs copies it into public/)
• lib/palette.generated.ts — for the OG cards and LogoMark, via the small lib/palette.ts wrapper (withAlpha)
• flutter/lib/support/palette.generated.dart — afLight/afDark for islandTheme
• landing/lib/palette.generated.dart — the landing's theme-color
• recolors SVG shapes marked data-palette="ctaYellow" in place, so the logos stay single files of artwork

npm run palette:check fails CI when any of them drifts (wired into docs.yml next to examples:check).

Also in here. The Fumadocs --color-fd-* variables are now @theme inline references to the tokens (no dark block, no third copy); alpha variants derive via color-mix() in CSS and withAlpha() in TS; the unused --af-accent-2 is gone (hover borders use the accent). Light theme values that the design system doesn't specify (body gray, strong hairline, the accent and signals as text on white) are named …OnLight tints in palette.json, derived from the design-system hues.

Also merged in: the landing's move to Jaspr @css getters (claude/busy-bell-xjh9eo, commit 9bd3648, combined in d1c5acc). landing.css is gone; every component styles itself next to its build, and lib/styles.dart holds the fonts, tokens, reset and utilities — ciach's structure. The palette plugs in the same way it does there: _tokens spreads afLight/afDark's cssVariables (no more typed-out colors), the hero glows, primary-button hover and pill wash derive through colorMix() and tokens, and --af-accent-2 is gone. Because main.server.dart now imports the gitignored main.server.options.dart that jaspr_builder writes, the docs CI runs dart run build_runner build before analyzing the landing page.

Also in here: every landing class has one owner (d55102a, from the review thread on button.dart). Each component keeps the classes it renders as typed ClassName constants and spells its selectors and classes: attributes from them; variants carry their class as enum values. Pieces two files styled or rendered by string are now components of their own — CopyButton, Logo (with large), ButtonRow (af-actions), the Card family in card.dart, the Section vocabulary (Eyebrow, Lead, Checklist, MoreLink, DemoSlot, Section.plain) — and styles.dart keeps exactly one class of its own, container. The names landing.js and the docs' global.css depend on are unchanged; the rendered stylesheet differs only in the moved and renamed rules, and both themes' screenshots pixel-match the previous build. Because one stylesheet covers the whole page, class names are locally scoped by jaspr_class_scope (e5b1952, 56a287c, from a git ref until the package is released). The mechanism started here as a ClassScope<T> in styles.dart that hashed the Type at runtime; it now lives in that package and computes the suffix at build time instead. A component carries @scopedCss and a part 'hero.scopes.dart'; the builder writes its scope into that part file from the component's package, path and name, and a check phase fails the build when two components anywhere in the package graph would share a suffix. _class('af-grid') then renders as af-grid-<suffix>, and ClassName.shared keeps the names landing.js and the docs' global.css know as written. The part files are generated on every build and not committed, so the docs workflow's build_runner step covers them next to the Jaspr options.

Out of scope on purpose: typography and shape (Space Grotesk / JetBrains Mono, the 14px radii and pill buttons stay).

Test plan

• npm run lint, npm run format, npm run types:check, npm run palette:check — clean
• dart analyze --fatal-infos and dart format --set-exit-if-changed in landing/ — clean
• dart format --set-exit-if-changed lib/support in docs_app/flutter under the package's 3.8 language version — clean
• npm run landing:build (Jaspr) and next build — succeed; /og/landing.png and /og/[...slug] prerender
• Landing refactor: rendered <style> diffed rule-by-rule against the previous build (only the moved/renamed rules differ); full-page screenshots of / in both themes pixel-match it
• Scoping: build_runner writes the 11 part files, jaspr build renders 67 scoped class names, and the names outside a component — af-landing, af-container, the af-example* and af-tab-input contract with landing.js and the docs' global.css — are unchanged. The suffixes moved when the mechanism did, so the class names in the screenshots above are one build behind; the pixels are not.
• Screenshots of /, /docs, /docs/faq in both themes via next start: computed --af-bg/--af-accent and --color-fd-* resolve to the palette in each theme, no page errors; both OG cards render with the new yellow
• flutter analyze / flutter test in docs_app/flutter — no Flutter SDK in my environment; CI's build job runs them
• Eyeball the preview: hero glow, the highlighter "Simple code." in light mode, a live demo's accent (yellow focus/buttons inside the island), docs callouts and diff markers

🤖 Generated with Claude Code

https://claude.ai/code/session_013Tw8hY1dZyp7s18pUTCacv

[github-actions]

Docs preview: https://advanced-forms-c0j0zh02h-leancode.vercel.app

Built from ce3a8ce; the landing page is at /, the docs under /docs.

[claude]

Merged claude/busy-bell-xjh9eo (the landing's move to Jaspr @css getters) into this branch in d1c5acc, with the palette wired into its styles.dart the way ciach does it — _tokens is written from afLight/afDark, the remaining literal colors became tokens and colorMix(), and CI now runs build_runner before analyzing the landing so the generated options exist. Verified: analyze, format (including the generated options), Jaspr build, palette:check, and renders in both themes. The busy-bell branch itself can be deleted once this lands.

🤖 Generated with Claude Code

---

Generated by Claude Code

[PiotrRogulski]

To iterate over such an ad-hoc collection, I'd use a list of pairs; might be simpler

[claude]

Done in 8d4cd30 — and one step simpler than pairs: the variable is always --tk-<token>, so it's now a plain list of the token names, for (final token in const ['keyword', 'type', …]) css('.tk-$token').styles(color: Color.variable('--tk-$token')).

🤖 Generated with Claude Code

---

Generated by Claude Code

[Komoszek]

We should definitely centralize the branding/colors do we don't end up with 1000 different palettes 🙈 the color generation script could definitely be improved, but it's really important

[Komoszek]

IMO we shouldn't mention ciach or aby other package that is not the real branding package (maybe we should create the company-wide branding package? 🤔 )

[claude]

Agreed — every ciach mention in the READMEs and code comments is gone in cb6d87e. On a company-wide branding package: palette.json is shaped for exactly that (the swatches named as the design system names them, the themes as tokens built from them), so lifting it and the generator out into a shared package is the natural next step — out of scope for this PR, though.

🤖 Generated with Claude Code

---

Generated by Claude Code

[Komoszek]

WDYT about extracting the af-button to some const and reusing it instead of the raw strings? The same applies to sll the other components

[claude]

Fair point, but it's a bigger bite than it looks here: 71 distinct classes across 125 selectors and 83 classes: strings in 10 components, and many selectors are compound (.af-button-primary:hover, .af-hero-grid > *) or shared between files. That code just landed with the @css refactor, so I'd rather not reshuffle it inside this PR — leaving the call to @PiotrRogulski whether to fold it in here or follow up separately.

🤖 Generated with Claude Code

---

Generated by Claude Code

[Komoszek]

Compound selectors arę not a problem, just do string interpolation. If for some reson we had to export the base classnames then IMO something iż wrong with the code. We shouldn't need to target the internal classname

[claude]

Measured it, and you're right that it isn't just a rename: of 82 classes, 17 cross a file boundary. 3 are the intended global utilities from styles.dart (af-container, af-landing, af-skip-link); the other 14 are real couplings — footer.dart renders hero.dart's af-hero-actions/af-center, sections.dart renders five of section.dart's classes (af-checklist, af-eyebrow, af-lead, af-section-demo, af-section-more), footer.dart styles nav_bar.dart's af-logo, and af-copy-idle/af-copy-done are styled in both hero.dart and example_frame.dart. Consts would surface each of those as an import, which is the point — but resolving them properly means moving shared rules (an actions row, a copy button, the logo) to shared homes, i.e. a component-boundary pass over the @css refactor rather than string interpolation alone. Happy to do it; whether here or as a follow-up is @PiotrRogulski's call.

🤖 Generated with Claude Code

---

Generated by Claude Code

[PiotrRogulski]

Do whatever you want, make it good, future-proof, and scalable 🥰

Listen to your heart, there's nothing else you can do
~Roxette

[claude]

Done in d55102a, and it went further than a rename.

Typed names. ClassName is an extension type over the string (in styles.dart); every component keeps the classes it renders as static const ClassNames and spells both sides from them — css(_hero.selector), '${_grid.selector} > *' for selectors, classes: _hero.name / (container + _grid).name for the attribute. Compound selectors are interpolation, as you said; + combines two classes on one element. Variants carry their class as enum values (ButtonVariant.primary.className, CopyButtonVariant), so 'af-button-${variant.name}' is gone.

Boundaries. The 14 real cross-file couplings I listed are resolved by giving the shared piece an owner rather than exporting base names:

• CopyButton — the hero's install line and the example toolbar rendered and styled the same af-copy-idle/done swap in two files, with a global [data-copied="true"] { !important } rule doing the work for both. One component now, two variants (framed, ghost), no !important.
• Logo — was a function in nav_bar.dart styled there, overridden by the footer (.af-footer-brand .af-logo img). Now its own component with large: true, and the theme-switch classes are af-logo-light/dark instead of borrowing af-theme-* from the toggle.
• ButtonRow — af-hero-actions (+ af-center) was used by the footer and the skill band and refined by .af-band .af-hero-actions; now af-actions with center/flush options.
• Card, CardGrid, CardIcon in card.dart — the mode cards reused af-card/af-feature-icon from Features.styles by string; both grids now compose these and pass their own className for their own rules.
• Eyebrow, Lead, Checklist, MoreLink, DemoSlot in section.dart — the section vocabulary sections.dart rendered by string; Section.plain covers the skill band's headerless section.
• The > * min-width rules moved from styles.dart to the grids they belong to; af-accent to the hero; af-landing and the skip link to App; rich/externalLink to text.dart. styles.dart exports exactly one class, container.

The one export in the other direction is CopyButton.labelClassName, which the hero's install line hides under 540px — a parent reaching into a child it composes, which I think is the legitimate case.

Kept as they are: the names landing.js looks up (af-example*, af-tab-input, af-code-panel) and the ones the docs' global.css shares for the frame and the logo. The README's Styles section describes the rule.

Verified: dart analyze --fatal-infos and dart format clean; the rendered <style> differs from the previous build only in the moved/renamed rules (166 of 193 rules byte-identical, the rest are the ones above); full-page screenshots of both themes pixel-match the previous build (light: 0 pixels; dark: the 36 pixels of the pulsing demo dot).

---

Generated by Claude Code

[Komoszek]

Are those swatches used anywhere? Dart counterparts uses them to build the themes, but both CSS and TS variants inlines the colors into the themes

[claude]

Yes — LogoMark in components/logo.tsx takes its yellow from swatches.ctaYellow (that is what keeps the docs favicon and the OG cards on the palette), and as of cb6d87e the TS themes are built from the swatches too, like the Dart ones: bg: swatches.white, accentSoft: withAlpha(swatches.ctaYellow, 0.45), with withAlpha emitted alongside and lib/palette.ts reduced to re-exports. The CSS stays resolved on purpose: a --lc-black-style indirection would add a hop nothing else reads, and resolved values are what you want to see in DevTools. If a consumer ever needs the swatches as CSS variables, that's a few lines in the generator.

🤖 Generated with Claude Code

---

Generated by Claude Code

[Komoszek]

Question, if some other component used raw af-footer classname then would we have name collision? Is there any way in jaspr to avoid that?

[claude]

Yes, it would collide, and Jaspr has nothing built in to stop it. The @css getters are collected into one global <style>; there are no CSS modules, no hashed class names, no scoping — Styles inline on an element is the only scoped form, and it can't express hover, media queries or descendants. So the guarantee has to come from us:

• By construction: a class exists only as a ClassName constant on the component that owns it, and everyone else gets to it through that component (composing it, or a public constant it exports). A raw 'af-footer' string in another file would be the one way to break that.
• By check, as of fee6bbb: tool/check_class_names.dart reads lib/ and fails when the same ClassName('…') literal is declared in two places, or when a class or selector is written as a raw string ('af-…', '.af-…') outside a declaration. It runs in the docs workflow right after dart analyze. I probed it with a duplicate af-footer, a raw classes: 'af-hero af-x' and a raw css('.af-band h2') — all three are reported with file and line.

It can't catch a string built at runtime that happens to spell an existing class, but nothing in the codebase does that now, and the check would flag the literal pieces of most attempts. The README's Styles section mentions it.

---

Generated by Claude Code

[Komoszek]

Revert this commit, I would prefere something more in line of css modules, idk, built time suffix scoped to the specific component, like some key or smth.

[claude]

Reverted in 9ddf572, and d804a71 does the CSS-modules thing instead.

ClassName now takes its owner: ClassName('af-footer', owner: SiteFooter) renders as af-footer-14zoy — the suffix is five base-36 digits of an FNV-1a hash of the owner's type name, computed when the static site is rendered, so it is stable across builds and short enough to read in the inspector. Two components can both call something af-grid and never meet in the stylesheet, and a raw 'af-footer' string anywhere else matches nothing. Nothing changes at the call sites: selectors and classes: are still spelled from the constant (css(_footer.selector), classes: (container + _grid).name), so the suffix is never written by hand. Variants carry it through their enum (af-button-eaqh0 af-button-secondary-eaqh0).

ClassName.shared('af-example') renders as written, for the names that are a contract with another file: what landing.js looks up (af-example*, af-tab-input, af-code-panel), what the docs' global.css uses for the same frame and logo, af-landing, and the af-container utility. styles.dart documents the rule; the README's Styles section too.

Verified: the rendered stylesheet with the suffixes stripped is rule-for-rule the same as the previous build, and full-page screenshots of both themes are pixel-identical (0 differing pixels).

---

Generated by Claude Code

[PiotrRogulski]

Why a custom hash and the built-in hashCode?

[Komoszek]

Could we somehow simplifi this? Is it possible to infer the type from the usage in class? Do not commit anything just answer the question

[claude]

Not from the enclosing class, no. Dart has no static self-type: inside class Hero, a static const _class = ClassScope() has nothing to infer T from — the enclosing declaration isn't part of the expression's type context, and typing the field (static const ClassScope<Hero> _class = …) just moves the name. There's no this in a static context, the @css getters have to be static for jaspr_builder to collect them, so there's no instance to take runtimeType from, and macros are gone. A StackTrace.current in the initializer would technically show Hero._class, but that's a trick I wouldn't put in a codebase.

The one way to get the owner for free is to make the names instances of something that knows its type — an enhanced enum per component:

enum _Hero with ClassNames {
  hero('af-hero'),
  grid('af-hero-grid');

  const _Hero(this.local);
  final String local;
}

css('${_Hero.grid.selector} > *')
div(classes: (container + _Hero.grid).name)

ClassNames is a mixin that scopes by runtimeType, so nothing is passed anywhere; the enum is the scope. It also absorbs the variant enums (_Button { button, primary, secondary }), which removes the _variantClass indirection. The cost: every call site changes from _grid to _Hero.grid, and each enum needs a distinct name (_Hero, _Footer, …) because that name is what gets hashed — the same one-name-per-component ClassScope<Hero>() spells today, just in a different place, and the same collision check would guard it.

Beyond that, the only route to zero declarations is a build_runner builder generating the scope per component. I wouldn't add a builder for one line.

My take: ClassScope<Hero>() is one line per component and leaves call sites alone; the enum is the same information with grouping and a bigger diff. Happy to switch if you prefer the grouping — say the word.

---

Generated by Claude Code

[PiotrRogulski]

Do you think it's possible to genericise it and package it for reuse in different Jaspr projects?

[claude]

Yes, and cheaply. Nothing in ClassScope/ClassName is specific to this site — or to Jaspr, for that matter: it's ~60 lines of dart:core that produce strings, and Jaspr only ever sees the strings (css(x.selector), classes: x.name). The project-specific parts (container, the af- prefix, which names are shared) stay on the consumer's side.

What a package would add beyond a copy-paste:

• Configurable scope: prefix, suffix length, and a strategy for the suffix. In particular a dev mode that renders af-hero-grid--Hero instead of af-hero-grid-174ao (what CSS modules do in development), switched by Jaspr.isDevelopment/kDebugMode or a builder flag, so the inspector reads like the source while jaspr build stays short and stable.
• Jaspr sugar: extension on ClassName { StyleRule styles(Styles) } so a rule is _grid.styles(display: .grid) instead of css(_grid.selector).styles(…), plus child, hover, descendant helpers for the compound selectors we currently spell as strings.
• The collision guard as it is, and a test helper (expectUniqueScopes()) for projects that want it in a test rather than at render time.
• Tests and a README with the "one scope per component, shared for contracts" convention, so the rule travels with the code.

Where: a small package in the leancodepl org — jaspr_scoped_classes or similar — used by ciach's website/ and this landing first (that's already two consumers, and ciach has the same "one component, one file, global stylesheet" shape), published to pub.dev once it stops moving. Since the core has no Jaspr dependency it could even be a plain Dart package with the Jaspr sugar as an optional import.

I'd do it as a follow-up rather than in this PR: extract the current code verbatim, add the dev-mode names and the sugar, then point both sites at it. Happy to open that PR when you want it.

---

Generated by Claude Code

[claude]

Update for this thread: as of e5b1952 the scoping no longer lives in this repo. It moved to jaspr_class_scope in flutter_corelibrary (pulled from a git ref until it's released), with a builder that answers both open questions here:

• Inferring the owner: a component carries @scopedCss and a part 'footer.scopes.dart'; the builder writes _$siteFooterScope into that part file, so static const _class = _$siteFooterScope — no type spelled, nothing hashed at runtime.
• The hash: computed at build time from the component's package, path and name, and the build fails on two components that would share a suffix.

ClassName.shared, .name, .selector and + are unchanged at the call sites; every suffix changes, so the class names in the earlier screenshots differ, the styles don't. styles.dart is back to fonts, tokens, reset and container. CI is green on e5b1952 and the README's Styles section describes the new shape.

---

Generated by Claude Code