Component Skills - defuss-shadcn

On this page (8)

§What is a component skill?

A component skill is a Markdown file that documents the HTML pattern for a component - what elements to use, which attributes to set, what variants and sizes are available, and the ARIA requirements. It's the single source of truth for how to write the markup.

Component skills don't contain CSS or JavaScript code - those live in their own files alongside the skill. The skill focuses purely on the HTML structure and its configuration options.

dist/components/{name}/

├── component-skill.md   ← the skill file (HTML reference)

├── {name}.css           ← component stylesheet

└── {name}.js            ← interaction JS (if needed)

§The SKILL.md index

dist/SKILL.md is the generated entry point of the whole system - integration instructions, the library's philosophy, a map of the dist/ layout, and one index entry per component (its taxonomy type, why to use it, when to reach for it, which files ship it, and which states it supports). It is built on every build from SKILL_tpl.md plus each skill's frontmatter, so it can never drift from the skills it indexes.

flowchart LR
    Skill["src/components/{name}/<br/>component-skill.md"]
    Tpl["src/SKILL_tpl.md"]
    Build["scripts/build.ts"]
    Dist["dist/components/{name}/<br/>component-skill.md"]
    Index["dist/SKILL.md"]
    Root["skills/defuss-shadcn/SKILL.md<br/>+ references/"]
    Verify{"scripts/verify.ts"}

    Skill --> Build
    Tpl --> Build
    Build --> Dist
    Build --> Index
    Build --> Root
    Verify -. "frontmatter" .-> Skill
    Verify -. "index fresh" .-> Index
    Verify -. "sources fresh" .-> Root

Every build regenerates both indexes from the skills; verify fails the build when a skill's frontmatter is missing or an index lags behind it.

If you are an agent wiring this library into a project, point yourself at dist/SKILL.md first - it tells you what to include, which skill to read next, and where the state screenshots live (screenshots/{light,dark}/{name}-{state}.png in the source repo), so you can look up exactly what an "open modal" or "collapsed sidebar" should look like before you build it.

§Skill file structure

Every component skill opens with a YAML frontmatter block and then follows a consistent template with these sections in order:

0. FrontmatterMachine-readable header (name, type, why, when, where, supportedStates) that SKILL.md is generated from - required on every skill and enforced by verify.1. Native basisWhich HTML element or browser API the component builds on. Every component starts from native semantics.2. Native Web APIsBulleted list of significant platform APIs used (Popover API, CSS Anchor Positioning, <dialog>, etc.) with MDN links.3. StructureComplete HTML markup showing the component's element hierarchy, class names, and required attributes.4. VariantsTable of data-variant values with descriptions and example markup.5. SizesTable of data-size values (if the component supports them).6. AccessibilityRequired ARIA attributes, keyboard interactions, and screen reader considerations.7. NotesEdge cases, composition tips, caveats, and integration notes.

§Component taxonomy

Every component is classified with exactly one type, expressed in three places that verify keeps in sync: the skill's type: frontmatter (source of truth), the sidebar badge, and the badge on the component's doc page. Classification never leaks into component names - Button, never ButtonAtom.

ATMAtom - contains no descendant components (any DOM inside, but no other component).

MOLMolecule - ≥1 direct child component, all atoms.

ORGOrganism - direct children are atoms and/or molecules, with ≥1 molecule.

BLKBlock - a self-contained sectional slice of a template (header, hero, pricing, footer…); arbitrary nesting inside.

TPLTemplate - the whole page/UI composition of blocks and anything else.

§Example: Badge skill file

Here's the complete skill file for the Badge component - one of the simplest components in the system.

---

name: Badge

type: ATM

why: Pure-CSS <span> chip with emphasis variants —

     nothing to wire up.

when: Short status, version, or count labels next to

      content - not for actions.

where: dist/components/badge/badge.css

supportedStates: default

---

# Pattern: Badge

## Native basis

`<span>` element. No interactivity required —

pure visual indicator.

---

## Native Web APIs

- [`<span>`](https://developer.mozilla.org/...)

  - inline container for phrasing content

---

## Structure

```html

<span class="badge" data-variant="default">

  Badge

</span>

```

---

## Variants

| `data-variant` | Purpose                    |

|----------------|----------------------------|

| `default`      | Primary bg, high emphasis  |

| `secondary`    | Secondary bg, medium       |

| `outline`      | Border only, low emphasis  |

```html

<span class="badge" data-variant="default">

New

</span>

<span class="badge" data-variant="secondary">

  Draft

</span>

<span class="badge" data-variant="outline">

  v0.1.0

</span>

```

---

## Accessibility

- Use descriptive text content - badges are

  read inline by screen readers.

- If the badge is purely decorative, add

  `aria-hidden="true"`.

§Using skills with AI assistants

Component skills are designed to give AI assistants everything they need to generate correct, accessible markup in a single reference. Here's how to use them:

Start at SKILL.mdGive the agent dist/SKILL.md as its entry point: it explains integration and philosophy once, then points at the right component skill - the agent only reads the skills it actually needs.Copy & pasteCopy the skill file content into your AI chat alongside your request. The AI will use it as context to generate correct markup.File referenceIn tools that support file context (Copilot, Cursor, etc.), point the AI at dist/components/{name}/component-skill.md.Multiple skillsFor pages with multiple components, provide all relevant skill files. The AI will compose them correctly.

Using the defuss-shadcn component system, build a

settings page with:

- A card containing a form with two text inputs

- A destructive button to delete the account

- A toast notification on save

Here are the component skills:

[paste card, form, input, button, and toast skills]

§Using skills as a human reference

Even without AI, skill files serve as quick references. Need to know what variants a Badge supports? Open component-skill.md and check the variants table. Need the exact ARIA attributes for a Combobox? The accessibility section has them.

Quick lookupSkill files are faster than searching through CSS for which data-variant values exist or scanning JS for keyboard bindings.Copy-paste HTMLThe Structure section gives you copy-paste-ready markup with all required attributes already in place.ARIA checklistThe Accessibility section doubles as a checklist to verify your implementation covers all accessibility requirements.

§Available skills

Every component in the library has a skill file at dist/components/{name}/component-skill.md, and all of them are listed with their why/when/where and supported states in dist/SKILL.md. Browse the component pages in the sidebar to see the full list. Each component's documentation page includes a link to view its skill file.

Comments, ideas or improvements? Edit this page's source on GitHub