@supersoniks/concorde 5.0.4 → 5.1.0

package/.agents/skills/concorde-component-docs/SKILL.md

@@ -0,0 +1,194 @@
+---
+name: concorde-component-docs
+description: >-
+  Writes and edits Concorde UI component documentation pages (*.md) in English
+  with consistent structure, tone, sonic-code examples, and API tables. Use when
+  creating or updating component docs under src/core/components/ui/, when
+  uniformizing documentation, or when the user references alert.md-style docs.
+---
+
+# Concorde component documentation
+
+Apply this skill when **creating** or **editing** a component doc page (typically `src/core/components/ui/<component>/<component>.md`).
+
+Canonical examples: `alert.md`, `badge.md`, `link.md`, `image.md`.
+
+## Workflow
+
+### Creating a new page
+
+1. Read the component implementation (`.ts` / props, slots, reflected attributes, defaults).
+2. Draft the **intro** (what it does, when to use it, 1–2 critical APIs).
+3. Add **feature sections** in order of reader need (basic → variants → composition → edge cases → a11y).
+4. Add one **`<sonic-code>`** example per section; group enum variants in a single demo when practical.
+5. End with **`## API reference`** (attributes table, slots table if any).
+6. Run the [quality checklist](#quality-checklist).
+
+### Editing an existing page
+
+1. Preserve working examples; only change prose/structure to match this guide.
+2. Do not duplicate `## API reference` blocks—merge into one.
+3. Align intro tone and section titles with sibling docs; add missing API rows from source.
+4. Keep demo markup valid; avoid unrelated refactors in examples.
+
+## Page structure
+
+```markdown
+# ComponentName
+
+[Intro paragraph: 1–3 sentences. Purpose, primary use case, key props/slots.]
+
+## Basic example
+[or first topical section, e.g. ## Type, ## Href, ## Rounded]
+
+[Optional short prose before the example.]
+
+<sonic-code>
+  <template>
+    ...
+  </template>
+</sonic-code>
+
+## [Feature or variant name]
+
+...
+
+## API reference
+
+| Attribute | Values | Description |
+|----------|---------|-------------|
+| ... | ... | ... |
+
+| Slot | Description |
+|------|-------------|
+| ... | ... |
+```
+
+### Title (`#`)
+
+- Singular component name, Title Case: `# Alert`, `# Badge`, `# Link`, `# Image`.
+- Match the public tag name conceptually (`sonic-alert` → Alert).
+
+### Intro (required for new-style docs)
+
+One tight paragraph immediately after the title:
+
+- State **what** the component does and **when** to choose it.
+- Call out **defaults** and **constraints** only if they prevent misuse.
+- Formatting:
+  - **Bold** for emphasis on behavior (not for every noun).
+  - API names and tags in backticks; when listing several, **do not put commas between inline-code spans** (rendered as adjacent `<code>`). Join with **`/`**, **`and`**, or separate clauses—e.g. `` `label` `` / `` `text` ``, not `` `label` ``, `` `text` ``.
+  - Cross-link related components in prose: “aligned with **`sonic-button`**”, “pair with **`ratio="1/1"`**”.
+
+Avoid marketing fluff, long tutorials, and repeating the API table in the intro.
+
+### Section headings (`##` / `###`)
+
+- **Sentence case** or short Title Case; be consistent within one file.
+- Name sections after **one concern**: `Status`, `Size`, `Dismissible`, `Accessibility (\`announce\`)`, `Prefix and suffix slots`.
+- Use `###` for sub-variants of the same feature (e.g. `### AutoActive Strict vs partial`).
+- Put **`## API reference`** last—never in the middle.
+
+Suggested order (omit what does not apply):
+
+1. Basic example / primary API
+2. Visual variants (`type` / `status` / `variant` / `size` / …)
+3. Content model (slots, `label` / `text`, rich content)
+4. Composition patterns (inside buttons, with links, …)
+5. Behavioral flags (`dismissible` / `announce` / `cover` / …)
+6. Accessibility (dedicated section when non-obvious)
+7. API reference
+
+### Prose before examples
+
+- **Default first**: “With no `status`, behavior is `default`.” “Default **`loading`** is `lazy`.”
+- **Enums inline** when short: `` `outline` `` — border and text in the `type` color.
+- **Requirements**: stable `` `id` `` required for `dismissForever`; parent must constrain width for `ellipsis`.
+- **Implementation notes** only when they change usage: `localStorage`; `role="alert"`; remount to replay transitions.
+- Length: 0–4 sentences per section; longer only for accessibility or non-obvious behavior.
+
+## Live examples (`<sonic-code>`)
+
+Wrap all demos:
+
+```html
+<sonic-code>
+  <template>
+    <!-- demo markup -->
+  </template>
+</sonic-code>
+```
+
+Conventions:
+
+- Use Tailwind layout utilities already used in the design system docs: `grid gap-4` / `flex flex-wrap gap-2` / `items-center`.
+- Show **all enum values** in one row/grid when demonstrating `type`, `status`, or `size`.
+- Label variants in the UI (badge text, caption `<p class="mt-2">`) when comparison matters.
+- Prefer realistic copy over “Lorem ipsum” unless demonstrating truncation or length.
+- Interactive demos (buttons that mutate DOM) are allowed when they teach behavior—add one sentence explaining what to click.
+- Do not wrap API tables or long prose inside `<sonic-code>`.
+
+## API reference
+
+### Attributes table
+
+```markdown
+| Attribute | Values | Description |
+|----------|---------|-------------|
+| `name` | `a` · `b` (default `a`) | One line: behavior + default + interaction with other props |
+```
+
+- Column headers exactly: **Attribute**, **Values**, **Description**.
+- **Values**: list allowed literals separated by **middle dot (` · `)** or **`…`** for ranges (`2xs` … `2xl`)—**never commas between backtick spans**. Put **(default `…`)** in this column or in Description—be consistent within the file.
+- **Description**: imperative, factual; mention side effects (`removes from DOM`, `ignored when \`cover\` is set`).
+- Document boolean attributes as boolean in the table; no need to say “true/false” unless ambiguous.
+
+### Slots table
+
+```markdown
+| Slot | Description |
+|------|-------------|
+| *(default)* | Main label / message body |
+| `icon` | Replaces the default `sonic-icon` |
+```
+
+- If the component has **no slots**, state it in prose under the attributes table (see `image.md`).
+- Use *(default)* for the unnamed slot.
+
+### Single API block
+
+One `## API reference` section per file. If the source doc has duplicates, consolidate without losing rows.
+
+## Voice and language
+
+- **English only** for user-facing doc text.
+- Present tense, second person avoided; address the integrator (“Set **`announce`** when…”).
+- Prefer precise verbs: surface, navigate, truncate, persist, intercept.
+- Do not document internal CSS class names unless the doc already uses them for styling hooks (`[&[active]]:text-success` in examples is OK).
+
+## Quality checklist
+
+Before finishing, verify:
+
+- [ ] `#` title + intro paragraph present (for new or modernized pages).
+- [ ] Every `##` section (except API) has a `<sonic-code>` example unless it is pure sub-prose under a parent demo.
+- [ ] Defaults and required attributes are stated in prose or API table.
+- [ ] Accessibility called out where behavior affects AT (roles, `alt`, decorative icons).
+- [ ] Exactly one `## API reference`; attributes and slots match the component source.
+- [ ] No duplicate sections; heading levels skip only when using `###` under `##`.
+- [ ] Attribute/slot names match the implementation (camelCase in docs).
+- [ ] No comma-separated lists of inline-code terms in prose or API **Values** cells.
+
+## Anti-patterns
+
+- Long narrative guides, installation steps, or changelog in component `.md` files.
+- Examples without `<sonic-code>` wrappers.
+- API tables at the top of the page.
+- Mixing French and English in the same page.
+- Vague intros (“This component is very useful”) without API hints.
+- Separate micro-sections per enum value when one grid demo suffices.
+- Comma chains of inline code: `` `a` ``, `` `b` ``, and `` `c` `` (use `/`, ` · `, or `and` instead).
+
+## Reference template
+
+See [template.md](template.md) for a copy-paste skeleton.

package/.agents/skills/concorde-component-docs/template.md

@@ -0,0 +1,45 @@
+# ComponentName
+
+One paragraph: what **`sonic-component`** does, when to use it instead of alternatives, and the most important `` `attributes` `` / slots. Mention defaults only if they prevent mistakes.
+
+## Basic example
+
+<sonic-code>
+  <template>
+    <sonic-component>Minimal usage</sonic-component>
+  </template>
+</sonic-code>
+
+## Variant or feature name
+
+Short explanation of default and allowed values.
+
+<sonic-code>
+  <template>
+    <div class="flex flex-wrap gap-2">
+      <sonic-component>Default</sonic-component>
+      <sonic-component type="primary">Primary</sonic-component>
+    </div>
+  </template>
+</sonic-code>
+
+## Accessibility
+
+When screen readers or keyboard users need special handling.
+
+<sonic-code>
+  <template>
+    <sonic-component aria-label="…">…</sonic-component>
+  </template>
+</sonic-code>
+
+## API reference
+
+| Attribute | Values | Description |
+|----------|---------|-------------|
+| `example` | `a` · `b` (default `a`) | Behavior in one line |
+
+| Slot | Description |
+|------|-------------|
+| *(default)* | Primary content |
+| `named` | Optional slot purpose |