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..d2aa196 --- /dev/null +++ b/skills/css-containers/SKILL.md @@ -0,0 +1,112 @@ +--- +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, 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 + - 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); + } +} +``` + +Whoever lays out a row makes it a container the same way, for the components in it to follow: + +```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 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/css-light-dark/SKILL.md b/skills/css-light-dark/SKILL.md new file mode 100644 index 0000000..2bcd8e9 --- /dev/null +++ b/skills/css-light-dark/SKILL.md @@ -0,0 +1,200 @@ +--- +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; 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 + - 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 theme switch + +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' + +/** + * 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') + } +} + +/** + * 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 + } + + 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; +} +``` diff --git a/skills/ui-component/SKILL.md b/skills/ui-component/SKILL.md index 42cf111..0c671d2 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 @@ -73,48 +73,6 @@ 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; - } - ``` - ## UX & A11y - Apply core accessibility practices.