class-reference

# Class reference front matter Every component page carries a `classnames` block in its front matter. `DocsClassnames.astro` renders it as a table at the end of the page, `docs/pages/llms.txt.ts` reprints it for agents, and `docs/content.config.ts` validates it. Editing the table means editing the front matter — there is no markdown table to touch. ## 1. Shape ```yaml classnames: component: - class: alert desc: Container element part: - class: alert-icon desc: Icon slot, sized and colored with the alert color: - class: alert-{color} desc: Any base color, for example alert-success or alert-blue ``` The schema is strict (`docs/content.config.ts`), so a mistyped key fails the build. Each entry takes `class`, `desc`, and optionally `default: true`, which renders a "default" badge. ## 2. The eight types Rendered in this order regardless of the order in the file, so group by meaning rather than by position: | Type | Holds | Examples | | --- | --- | --- | | `component` | the class that makes the thing | `alert`, `btn`, `card` | | `part` | sub-elements it is built from | `card-header`, `alert-icon` | | `style` | surface treatment | `btn-outline`, `btn-ghost`, `alert-minor` | | `modifier` | shape or box changes | `btn-pill`, `btn-square`, `accordion-flush` | | `behavior` | state and motion | `btn-loading`, `icon-pulse`, `table-hover` | | `direction` | placement and orientation | `offcanvas-start`, `steps-vertical` | | `color` | color variants | `alert-{color}`, `btn-{color}` | | `size` | size variants | `btn-sm`, `avatar-{size}` | The split between `style`, `modifier` and `behavior` follows daisyUI: how it looks, what shape it is, how it reacts. ## 3. Collapse generated families Tabler generates colors, sizes, breakpoints and directions with loops. Listing each one turns a reference into a wall — `btn` alone compiles to 141 classes. Write one row with a brace placeholder and say what fills it: ```yaml - class: btn-{color} desc: Any base or social color, for example btn-primary or btn-facebook - class: table-mobile-{breakpoint} desc: Stacks rows into blocks below the breakpoint - class: switch-icon-slide-{direction} desc: Slides the icons; up, down, left, right, start or end ``` Collapse when the family is mechanical and complete. Keep separate rows when the members differ in meaning — `btn-sm`, `btn-lg` and `btn-xl` are worth spelling out, `flag-country-{code}` is not (258 members). ## 4. Leave out - Classes a script toggles rather than an author writes: `carousel-item-next`, `modal-backdrop`, `accordion-collapse`, `active`, `show`. - Bootstrap utilities that are not part of the component. - Classes that do not exist. This is the failure mode to guard against — see section 6. ## 5. Writing the description Say what the class does, from the rule, not from the name: - `alert-minor` — "Drops the tinted background, keeps a plain border", not "minor style". - `td-truncate` — "Cell whose content is cut with an ellipsis instead of stretching the table". One line, no trailing period needed, simple English. Read the SCSS before writing: ```shell sed -n '/^\.alert-minor/,/}/p' core/scss/ui/_alerts.scss ``` ## 6. Check every class exists Descriptions are hand-written, so a class can be invented or survive a rename. Three wrong entries were caught this way while the tables were first written — `trending` and `map` were never classes at all, and `.map` matched only a stray fragment in the compiled CSS. Verify against the compiled stylesheet, and confirm the rule has a body rather than trusting a text match: ```shell python3 -c " import re css = open('core/dist/css/tabler.css').read() for c in ['alert-minor', 'alert-icon']: m = re.search(r'(^|\})\s*\.' + c + r'\s*\{([^}]*)\}', css) print(c, '->', ' '.join(m.group(2).split())[:70] if m else 'NOT A RULE') " ``` Plugin classes live in their own sheets — `tabler-flags.css`, `tabler-socials.css`, `tabler-payments.css`, `tabler-vendors.css` — so read the right one. Components with no class of their own are real: `trending` is built from `text-green` plus an arrow icon, and the map page frames an embed with `ratio`. Document what the page actually uses. ## 7. Also set `source` Pages that carry `classnames` should carry `source` too — the repo-relative file that implements the component, rendered as the "Source code" link: ```yaml source: core/scss/ui/_alerts.scss ``` Most map to `core/scss/ui/_<name>s.scss`. Exceptions worth knowing: `segmented-control` → `_segmented.scss`, `step` → `_steps.scss`, `star-rating` → `_stars.scss`, `divider` → `_type.scss`, `tab` → `_nav.scss`, `tooltip` → `bootstrap/_tooltip.scss`, `trending` → `shared/ui/Trending.astro`. ## 8. Finish - Load the page and confirm the table renders and "Class reference" reaches the "On this page" rail. - Run `pnpm run lint` and `pnpm --dir docs run type-check`. - New pages also need a menu entry in `shared/data/docs.json` — see the write-docs skill.