Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
112 changes: 112 additions & 0 deletions skills/css-containers/SKILL.md
Original file line number Diff line number Diff line change
@@ -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 (
<div
className={clsx(styles.root, styles[variant], variant === 'tiles' && containers.tiles, className)}
{...props}
>
{children}
</div>
)
}
```

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
<div className={clsx(styles.root, containers.toolbar, className)}>
{/* the search, the filter, the actions */}
</div>
```

## 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.
200 changes: 200 additions & 0 deletions skills/css-light-dark/SKILL.md
Original file line number Diff line number Diff line change
@@ -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(<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
<head>
<!-- The browser paints its canvas and controls in the system's theme before the stylesheets come -->
<meta name="color-scheme" content="light dark">
<!-- The theme chosen; a browser that refuses storage throws, and keeps the system's -->
<script>
try {
const theme = localStorage.getItem('theme')

if (theme === 'light' || theme === 'dark') {
document.documentElement.dataset.theme = theme
document.documentElement.style.colorScheme = theme
}
} catch {}
</script>
<link rel="stylesheet" href="/styles.css">
</head>
```

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 `<html>` finds two attributes there it didn't render: let it keep them, as React's `suppressHydrationWarning` on `<html>` does.
- A color reads its token, never `data-theme`. The attribute is for what a token can't switch, a picture: a `<source media>` 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;
}
```
44 changes: 1 addition & 43 deletions skills/ui-component/SKILL.md
Original file line number Diff line number Diff line change
@@ -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
Expand Down Expand Up @@ -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(<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.
Expand Down