class-reference✓ Pass

SKILL.md Content

---
name: class-reference
description: Write or update the `classnames` front matter that renders the class reference table on a Tabler docs page. Use whenever a component page needs its class list added, a component gains or loses a class in `core/scss/**`, or the user asks for a class reference, a class table, or a `classnames` block. Also consult it proactively after adding a class to an existing component, since the table is hand-written and will not notice on its own.
---

# 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.

License

Declared license: MIT

MIT License

Copyright (c) 2018 tabler

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

View the license in the source repository — the version published there is authoritative.