From 65bfcd86467bb516051ee2a4d6d24c3bb9180e74 Mon Sep 17 00:00:00 2001 From: dangreen Date: Thu, 19 Nov 2026 20:10:07 +0400 Subject: [PATCH 1/4] chore: add css-containers and css-light-dark skills Move the light and dark theme rules out of the ui-component skill into css-light-dark, which also shows how to keep `light-dark()` native through Lightning CSS, and point ui-component to both new skills. --- README.md | 2 + skills/css-containers/SKILL.md | 109 +++++++++++++++++++++++++++++++++ skills/css-light-dark/SKILL.md | 84 +++++++++++++++++++++++++ skills/ui-component/SKILL.md | 46 +------------- 4 files changed, 198 insertions(+), 43 deletions(-) create mode 100644 skills/css-containers/SKILL.md create mode 100644 skills/css-light-dark/SKILL.md diff --git a/README.md b/README.md index 9174841..c3b87ce 100644 --- a/README.md +++ b/README.md @@ -25,6 +25,8 @@ Scripts and configs for TrigenSoftware's projects. - [`flat-layers-design`](skills/flat-layers-design/SKILL.md) - [`eslint-to-oxlint`](skills/eslint-to-oxlint/SKILL.md) - [`css-mixin`](skills/css-mixin/SKILL.md) +- [`css-containers`](skills/css-containers/SKILL.md) +- [`css-light-dark`](skills/css-light-dark/SKILL.md) - [`ui-component`](skills/ui-component/SKILL.md) - [`react-component`](skills/react-component/SKILL.md) - [`nanoviews-component`](skills/nanoviews-component/SKILL.md) diff --git a/skills/css-containers/SKILL.md b/skills/css-containers/SKILL.md new file mode 100644 index 0000000..46cc7f3 --- /dev/null +++ b/skills/css-containers/SKILL.md @@ -0,0 +1,109 @@ +--- +name: css-containers +description: Pattern for named CSS container queries in a CSS Modules codebase — every container name is a class in one shared CSS Module, the only place that declares `container:`, put on the element that is the container; parts query the name with `@container`. Covers why the names are global tokens, how they follow the layers' dependency direction, and when a container stays unnamed. Apply when adding a container query, a container, or a part that follows its parent's width. +license: MIT +compatibility: + - Claude Code + - Codex + - Cursor + - Gemini CLI + - GitHub Copilot + - Windsurf + - Cline + - Roo Code + - Goose + - Continue + - OpenCode + - Amp + - universal +metadata: + author: dangreen + tags: + - css + - css-modules + - container-queries + - ui +--- + +# CSS Containers + +A named container query is a dependency between stylesheets: one element is the container, and the parts inside it query its width. In a CSS Modules codebase the names are tokens, as colors and sizes are: + +- every container name is a class in one shared CSS Module, e.g. `containers.module.css`, and that file is the only place that declares `container:`; +- to make an element a container, add its class to the element; +- a part that follows the width queries the name with `@container`. + +## Example + +The container names, each with what carries it and what reads it: + +```css +/* containers.module.css */ + +/* A grid of tiles, `Grid variant='tiles'`. Read by Grid and by the tiles, which close up at 420 + or less. */ + +.tiles { + container: tiles / inline-size; +} + +/* A page's row of a search, its filters and its actions. Read by the filter's trigger, which + chooses its words by the room its row leaves. */ + +.toolbar { + container: toolbar / inline-size; +} +``` + +The component that is the container puts the class on itself: + +```tsx +import clsx from 'clsx' +import containers from '~/uikit/containers.module.css' +import styles from './Grid.module.css' + +export function Grid({ + className, + variant = 'fields', + children, + ...props +}) { + return ( +
+ {children} +
+ ) +} +``` + +A part queries the name in its own stylesheet: + +```css +/* ChoiceCard.module.css */ +@container tiles (max-width: 420px) { + .tile .text { + font-size: var(--sizeFont12); + } +} +``` + +A row that a business block lays out takes a container of the kit's the same way: + +```tsx +
+ {/* the search, the filter, the actions */} +
+``` + +## Rules + +- **The names are global.** A query reads a name declared in another file, and CSS Modules has no way to import one: Lightning CSS supports neither `@value` nor ICSS `:import`/`:export`, its `from` references cover classes (`composes`) and dashed idents (`var(--x from './file.css')`) alone, and a query's prelude takes no `var()`. Turn off the hashing of container names where the implementation does it, e.g. Lightning CSS's `cssModules: { container: false }`, which Vite takes as `css.lightningcss.cssModules`. Hashed, a name declared in one module and queried in another silently matches nothing. +- **A name is a token, named by its role:** `tiles`, `toolbar`, `search-band`, `card-body`. Never after one component (`media-card`) and never after a block or a page. The name is kebab-case, as stylelint's `value-keyword-case` keeps a keyword lower-case, and its class is the camelCase form CSS Modules want: `.cardBody` makes `card-body`. +- **The shared file is the registry.** Each class says what the container is, what carries it and what reads it. A new name goes there first; nothing writes `container:` anywhere else. +- **Dependencies follow the layers** (see the `flat-layers-design` skill). The names belong to the UI kit, as its design tokens do. A kit component queries the kit's names alone. A business block may put a kit's container class on a row it lays out and may query a kit's name for its own layout, but never names a container that a kit component reads: the kit would then depend on the block. +- **One container class per element.** `container` is one property, so a second class on the same element overrides the first. An element that must be two containers gets one class in the shared file that names both: `container: toolbar search-band / inline-size`. +- **An unnamed container stays local.** An element that measures itself for its own parts alone takes `container-type: inline-size` in its own stylesheet, with no name. An unnamed `@container (…)` query and the `cqi`/`cqw` units read the nearest container, whatever its name, so they serve that element's own parts alone; whatever another module queries gets a name, and so a class in the shared file. +- **Containment has a cost.** `inline-size` containment makes the element's inline size independent of its content: a container is an element whose width comes from its parent, a grid track or a block-level row, never one that should shrink to its content. diff --git a/skills/css-light-dark/SKILL.md b/skills/css-light-dark/SKILL.md new file mode 100644 index 0000000..f617a90 --- /dev/null +++ b/skills/css-light-dark/SKILL.md @@ -0,0 +1,84 @@ +--- +name: css-light-dark +description: Light and dark theme in native CSS — color tokens as `light-dark()` pairs on `:root` with `color-scheme`, so the site follows the system; a forced `color-scheme` for a theme switch or a preview toolbar; keeping `light-dark()` native through the build; and a theme class with a palette of its own for widgets on someone else's page. Apply when defining color tokens, adding a dark theme, or wiring a theme switch. +license: MIT +compatibility: + - Claude Code + - Codex + - Cursor + - Gemini CLI + - GitHub Copilot + - Windsurf + - Cline + - Roo Code + - Goose + - Continue + - OpenCode + - Amp + - universal +metadata: + author: dangreen + tags: + - css + - theme + - dark-mode + - color-scheme + - ui +--- + +# CSS Light and Dark + +- Make the tokens `light-dark(, )` pairs on `:root` with `color-scheme: light dark`, so the site follows the system. A `color-scheme` set on the root element forces one scheme, which is how the Storybook toolbar switches it: + + ```css + /* uikit/variables.css */ + :root { + --colorBackground: light-dark(#f2f2f4, #1d1d1f); + --colorText: light-dark(#1d1d1f, #ececee); + /* light-dark() takes colors alone: a shadow gets one for each of its colors */ + --shadowCard: 0 1px 2px light-dark(rgb(0 0 0 / 12%), rgb(0 0 0 / 40%)); + /* ... */ + + color-scheme: light dark; + } + ``` + +- Don't put tokens behind `@media (prefers-color-scheme: dark)`: they follow the system and nothing else, and no forced scheme reaches them. +- Keep `light-dark()` native in the built CSS: lightningcss compiles it for older targets into variables switched by `prefers-color-scheme`, which a forced `color-scheme` can't reach. Exclude the feature from its transforms: + + ```js + // vite.config.js + import { Features } from 'lightningcss' + + export default { + css: { + transformer: 'lightningcss', + lightningcss: { + exclude: Features.LightDark + } + } + } + ``` + +- A site's own theme switch forces the scheme on the root the same way, so the tokens stay `light-dark()` pairs. +- A theme class with a palette of its own is for exceptional cases, such as DevTools that sit on someone else's page and switch their own theme: the root is not theirs to set. Their tokens live on the class: the default palette on `.root`, the other one on a modifier that redefines the colors. Each sets its `color-scheme`, so native controls and scrollbars follow: + + ```css + /* uikit/Theme/Theme.module.css */ + .root { + --colorBackground: #1d1d1f; + --colorText: #ececee; + /* ... */ + + color-scheme: dark; + color: var(--colorText); + } + + .light { + --colorBackground: #f2f2f4; + --colorText: #1d1d1f; + /* ... */ + + color-scheme: light; + } + ``` diff --git a/skills/ui-component/SKILL.md b/skills/ui-component/SKILL.md index 42cf111..d7b8431 100644 --- a/skills/ui-component/SKILL.md +++ b/skills/ui-component/SKILL.md @@ -1,6 +1,6 @@ --- name: ui-component -description: Framework-agnostic rules for writing UI components — semantic HTML, CSS Modules conventions (root class, camelCase, CSS Custom Properties), light and dark theme tokens, and UX/accessibility requirements. Apply when creating, editing, or reviewing UI components, their markup, or styles. +description: Framework-agnostic rules for writing UI components — semantic HTML, CSS Modules conventions (root class, camelCase, CSS Custom Properties), and UX/accessibility requirements. Apply when creating, editing, or reviewing UI components, their markup, or styles. license: MIT compatibility: - Claude Code @@ -72,48 +72,8 @@ metadata: ``` - Implement responsiveness via CSS, not JS (`userAgent`/`matchMedia`/…) — it keeps server-side rendering simple. - -## Light and dark theme - -- Make the tokens `light-dark(, )` pairs on `:root` with `color-scheme: light dark`, so the site follows the system. A `color-scheme` set on the root element forces one scheme, which is how the Storybook toolbar switches it: - - ```css - /* uikit/variables.css */ - :root { - --colorBackground: light-dark(#f2f2f4, #1d1d1f); - --colorText: light-dark(#1d1d1f, #ececee); - /* light-dark() takes colors alone: a shadow gets one for each of its colors */ - --shadowCard: 0 1px 2px light-dark(rgb(0 0 0 / 12%), rgb(0 0 0 / 40%)); - /* ... */ - - color-scheme: light dark; - } - ``` - -- Don't put tokens behind `@media (prefers-color-scheme: dark)`: they follow the system and nothing else, and no forced scheme reaches them. -- Keep `light-dark()` native in the built CSS: lightningcss compiles it for older targets into variables switched by `prefers-color-scheme`, which a forced `color-scheme` can't reach. -- A site's own theme switch forces the scheme on the root the same way, so the tokens stay `light-dark()` pairs. -- A theme class with a palette of its own is for exceptional cases, such as DevTools that sit on someone else's page and switch their own theme: the root is not theirs to set. Their tokens live on the class: the default palette on `.root`, the other one on a modifier that redefines the colors. Each sets its `color-scheme`, so native controls and scrollbars follow: - - ```css - /* uikit/Theme/Theme.module.css */ - .root { - --colorBackground: #1d1d1f; - --colorText: #ececee; - /* ... */ - - color-scheme: dark; - color: var(--colorText); - } - - .light { - --colorBackground: #f2f2f4; - --colorText: #1d1d1f; - /* ... */ - - color-scheme: light; - } - ``` +- A part that follows its parent's width uses a named container from the shared containers module — see the `css-containers` skill. +- Color tokens for a light and a dark theme are `light-dark()` pairs — see the `css-light-dark` skill. ## UX & A11y From ba03b76b9061a0482d47dc3247f253f0584c85ce Mon Sep 17 00:00:00 2001 From: dangreen Date: Thu, 19 Nov 2026 20:13:17 +0400 Subject: [PATCH 2/4] chore: point ui-component to css-mixin and write doc comments in css-containers --- skills/css-containers/SKILL.md | 12 ++++++++---- skills/ui-component/SKILL.md | 1 + 2 files changed, 9 insertions(+), 4 deletions(-) diff --git a/skills/css-containers/SKILL.md b/skills/css-containers/SKILL.md index 46cc7f3..ffd7288 100644 --- a/skills/css-containers/SKILL.md +++ b/skills/css-containers/SKILL.md @@ -40,15 +40,19 @@ The container names, each with what carries it and what reads it: ```css /* containers.module.css */ -/* A grid of tiles, `Grid variant='tiles'`. Read by Grid and by the tiles, which close up at 420 - or less. */ +/** + * A grid of tiles, `Grid variant='tiles'`. Read by Grid and by the tiles, + * which close up at 420 or less. + */ .tiles { container: tiles / inline-size; } -/* A page's row of a search, its filters and its actions. Read by the filter's trigger, which - chooses its words by the room its row leaves. */ +/** + * A page's row of a search, its filters and its actions. Read by the filter's + * trigger, which chooses its words by the room its row leaves. + */ .toolbar { container: toolbar / inline-size; diff --git a/skills/ui-component/SKILL.md b/skills/ui-component/SKILL.md index d7b8431..2d2c0c5 100644 --- a/skills/ui-component/SKILL.md +++ b/skills/ui-component/SKILL.md @@ -74,6 +74,7 @@ metadata: - Implement responsiveness via CSS, not JS (`userAgent`/`matchMedia`/…) — it keeps server-side rendering simple. - A part that follows its parent's width uses a named container from the shared containers module — see the `css-containers` skill. - Color tokens for a light and a dark theme are `light-dark()` pairs — see the `css-light-dark` skill. +- A style several components share is a mixin, a class in the shared mixins module — see the `css-mixin` skill. ## UX & A11y From c826b930dd63768d783d1ea3cb5fbe4a6e717611 Mon Sep 17 00:00:00 2001 From: dangreen Date: Thu, 19 Nov 2026 20:17:45 +0400 Subject: [PATCH 3/4] chore: drop references to other skills from css-containers and ui-component --- skills/css-containers/SKILL.md | 9 ++++----- skills/ui-component/SKILL.md | 3 --- 2 files changed, 4 insertions(+), 8 deletions(-) diff --git a/skills/css-containers/SKILL.md b/skills/css-containers/SKILL.md index ffd7288..d2aa196 100644 --- a/skills/css-containers/SKILL.md +++ b/skills/css-containers/SKILL.md @@ -1,6 +1,6 @@ --- name: css-containers -description: Pattern for named CSS container queries in a CSS Modules codebase — every container name is a class in one shared CSS Module, the only place that declares `container:`, put on the element that is the container; parts query the name with `@container`. Covers why the names are global tokens, how they follow the layers' dependency direction, and when a container stays unnamed. Apply when adding a container query, a container, or a part that follows its parent's width. +description: Pattern for named CSS container queries in a CSS Modules codebase — every container name is a class in one shared CSS Module, the only place that declares `container:`, put on the element that is the container; parts query the name with `@container`. Covers why the names are global tokens, why one file declares them all, and when a container stays unnamed. Apply when adding a container query, a container, or a part that follows its parent's width. license: MIT compatibility: - Claude Code @@ -94,7 +94,7 @@ A part queries the name in its own stylesheet: } ``` -A row that a business block lays out takes a container of the kit's the same way: +Whoever lays out a row makes it a container the same way, for the components in it to follow: ```tsx
@@ -105,9 +105,8 @@ A row that a business block lays out takes a container of the kit's the same way ## Rules - **The names are global.** A query reads a name declared in another file, and CSS Modules has no way to import one: Lightning CSS supports neither `@value` nor ICSS `:import`/`:export`, its `from` references cover classes (`composes`) and dashed idents (`var(--x from './file.css')`) alone, and a query's prelude takes no `var()`. Turn off the hashing of container names where the implementation does it, e.g. Lightning CSS's `cssModules: { container: false }`, which Vite takes as `css.lightningcss.cssModules`. Hashed, a name declared in one module and queried in another silently matches nothing. -- **A name is a token, named by its role:** `tiles`, `toolbar`, `search-band`, `card-body`. Never after one component (`media-card`) and never after a block or a page. The name is kebab-case, as stylelint's `value-keyword-case` keeps a keyword lower-case, and its class is the camelCase form CSS Modules want: `.cardBody` makes `card-body`. -- **The shared file is the registry.** Each class says what the container is, what carries it and what reads it. A new name goes there first; nothing writes `container:` anywhere else. -- **Dependencies follow the layers** (see the `flat-layers-design` skill). The names belong to the UI kit, as its design tokens do. A kit component queries the kit's names alone. A business block may put a kit's container class on a row it lays out and may query a kit's name for its own layout, but never names a container that a kit component reads: the kit would then depend on the block. +- **A name is a token, named by its role:** `tiles`, `toolbar`, `search-band`, `card-body`. Never after one component (`media-card`) and never after a page. The name is kebab-case, as stylelint's `value-keyword-case` keeps a keyword lower-case, and its class is the camelCase form CSS Modules want: `.cardBody` makes `card-body`. +- **The shared file is the registry.** Each class says what the container is, what carries it and what reads it. A new name goes there first; nothing writes `container:` anywhere else. A component thus depends on the shared file alone, as on the design tokens, never on a name its consumer made up. - **One container class per element.** `container` is one property, so a second class on the same element overrides the first. An element that must be two containers gets one class in the shared file that names both: `container: toolbar search-band / inline-size`. - **An unnamed container stays local.** An element that measures itself for its own parts alone takes `container-type: inline-size` in its own stylesheet, with no name. An unnamed `@container (…)` query and the `cqi`/`cqw` units read the nearest container, whatever its name, so they serve that element's own parts alone; whatever another module queries gets a name, and so a class in the shared file. - **Containment has a cost.** `inline-size` containment makes the element's inline size independent of its content: a container is an element whose width comes from its parent, a grid track or a block-level row, never one that should shrink to its content. diff --git a/skills/ui-component/SKILL.md b/skills/ui-component/SKILL.md index 2d2c0c5..0c671d2 100644 --- a/skills/ui-component/SKILL.md +++ b/skills/ui-component/SKILL.md @@ -72,9 +72,6 @@ metadata: ``` - Implement responsiveness via CSS, not JS (`userAgent`/`matchMedia`/…) — it keeps server-side rendering simple. -- A part that follows its parent's width uses a named container from the shared containers module — see the `css-containers` skill. -- Color tokens for a light and a dark theme are `light-dark()` pairs — see the `css-light-dark` skill. -- A style several components share is a mixin, a class in the shared mixins module — see the `css-mixin` skill. ## UX & A11y From e1febcf31658c2e1213a9502dd3f1f02b4790742 Mon Sep 17 00:00:00 2001 From: dangreen Date: Thu, 19 Nov 2026 20:23:06 +0400 Subject: [PATCH 4/4] chore: show a server-rendered site's theme switch in css-light-dark skill --- skills/css-light-dark/SKILL.md | 150 +++++++++++++++++++++++++++++---- 1 file changed, 133 insertions(+), 17 deletions(-) diff --git a/skills/css-light-dark/SKILL.md b/skills/css-light-dark/SKILL.md index f617a90..2bcd8e9 100644 --- a/skills/css-light-dark/SKILL.md +++ b/skills/css-light-dark/SKILL.md @@ -1,6 +1,6 @@ --- name: css-light-dark -description: Light and dark theme in native CSS — color tokens as `light-dark()` pairs on `:root` with `color-scheme`, so the site follows the system; a forced `color-scheme` for a theme switch or a preview toolbar; keeping `light-dark()` native through the build; and a theme class with a palette of its own for widgets on someone else's page. Apply when defining color tokens, adding a dark theme, or wiring a theme switch. +description: Light and dark theme in native CSS — color tokens as `light-dark()` pairs on `:root` with `color-scheme`, so the site follows the system; keeping `light-dark()` native through the build; a theme switch that forces `color-scheme` on the root, keeps the choice in `localStorage` and sets it from an inline script in the head, so a server-rendered page opens in the chosen theme; pictures drawn for one theme; and a theme class with a palette of its own for widgets on someone else's page. Apply when defining color tokens, adding a dark theme, or wiring a theme switch. license: MIT compatibility: - Claude Code @@ -60,25 +60,141 @@ metadata: } ``` -- A site's own theme switch forces the scheme on the root the same way, so the tokens stay `light-dark()` pairs. -- A theme class with a palette of its own is for exceptional cases, such as DevTools that sit on someone else's page and switch their own theme: the root is not theirs to set. Their tokens live on the class: the default palette on `.root`, the other one on a modifier that redefines the colors. Each sets its `color-scheme`, so native controls and scrollbars follow: +## A theme switch - ```css - /* uikit/Theme/Theme.module.css */ - .root { - --colorBackground: #1d1d1f; - --colorText: #ececee; - /* ... */ +A site's own theme switch forces the scheme on the root the same way, so the tokens stay `light-dark()` pairs. The choice is the browser's, kept in `localStorage`, never in a cookie or the account: the server renders one page for everyone, and a visitor without an account can choose too. The page's head sets it before the stylesheets arrive, so a server-rendered page opens in the chosen theme, never in the system's first: + +```html + + + + + + + +``` + +The switch keeps the choice and sets it the same way. System sets nothing, and the root's `color-scheme: light dark` follows the device again: + +```ts +// theme.ts +export type Theme = 'system' | 'light' | 'dark' + +// The key the head's script reads too +const THEME_KEY = 'theme' - color-scheme: dark; - color: var(--colorText); +/** + * Sets a theme on the root: `color-scheme` picks each token's half, and `data-theme` serves what + * a token can't switch, such as a picture drawn for one theme. + * @param theme - The theme; anything but `light` and `dark` is the system's. + */ +export function applyTheme(theme: string | null) { + const root = document.documentElement + + if (theme === 'light' || theme === 'dark') { + root.dataset.theme = theme + root.style.colorScheme = theme + } else { + root.removeAttribute('data-theme') + root.style.removeProperty('color-scheme') } +} - .light { - --colorBackground: #f2f2f4; - --colorText: #1d1d1f; - /* ... */ +/** + * Keeps the theme chosen and sets it. + * @param theme - The theme chosen. + */ +export function setTheme(theme: Theme) { + try { + if (theme === 'system') { + localStorage.removeItem(THEME_KEY) + } else { + localStorage.setItem(THEME_KEY, theme) + } + } catch { + // A browser that refuses storage keeps the choice for this page alone + } - color-scheme: light; + applyTheme(theme) +} + +/** + * Follows a theme chosen in another tab. + * @returns Stops following. + */ +export function syncTheme() { + function onStorage(event: StorageEvent) { + if (event.key === THEME_KEY) { + applyTheme(event.newValue) + } } - ``` + + window.addEventListener('storage', onStorage) + + return () => window.removeEventListener('storage', onStorage) +} +``` + +A picture drawn in one theme's inks, such as a logo, has no token to switch: it comes twice, and the theme hides one of the two. With no theme chosen, the system's decides: + +```css +/* mixins.module.css */ + +/** + * `hideDark` on a picture drawn for the light theme, `hideLight` on its twin for the dark one. + */ + +:root[data-theme='dark'] .hideDark, +:root[data-theme='light'] .hideLight { + display: none; +} + +@media (prefers-color-scheme: dark) { + :root:not([data-theme]) .hideDark { + display: none; + } +} + +@media (prefers-color-scheme: light) { + :root:not([data-theme]) .hideLight { + display: none; + } +} +``` + +- Nothing the server renders shows the choice: the server doesn't know it, and the browser's first render would differ from the HTML. A control that shows it, such as a menu's checked item, reads it in the browser, once the menu opens. +- A framework that hydrates `` finds two attributes there it didn't render: let it keep them, as React's `suppressHydrationWarning` on `` does. +- A color reads its token, never `data-theme`. The attribute is for what a token can't switch, a picture: a `` reads the system's theme alone, and an SVG picture's own `prefers-color-scheme` doesn't follow the page in Safari 18, which draws its light inks whatever the theme. + +## A theme class + +A theme class with a palette of its own is for exceptional cases, such as DevTools that sit on someone else's page and switch their own theme: the root is not theirs to set. Their tokens live on the class: the default palette on `.root`, the other one on a modifier that redefines the colors. Each sets its `color-scheme`, so native controls and scrollbars follow: + +```css +/* uikit/Theme/Theme.module.css */ +.root { + --colorBackground: #1d1d1f; + --colorText: #ececee; + /* ... */ + + color-scheme: dark; + color: var(--colorText); +} + +.light { + --colorBackground: #f2f2f4; + --colorText: #1d1d1f; + /* ... */ + + color-scheme: light; +} +```