@supersoniks/concorde 5.0.3 → 5.0.5

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 |

package/ai/cursor/rules/concorde-theme.mdc

@@ -8,6 +8,6 @@ alwaysApply: false
 
 Skill **`concorde-theme`**
 
-- `<sonic-theme background color font>` + `--sc-*` CSS variables
+- `<sonic-theme color font class="block bg-base">` + `--sc-*` CSS variables
 - `theme="dark"` for built-in dark palette
 - Not for `serviceURL` / API — use **`concorde-scope`**

package/ai/cursor/rules/concorde.mdc

@@ -53,7 +53,7 @@ Placeholder `${prop}` = chaîne normale, résolu depuis le composant hôte.
   par `get` pour `refetch`.
 - **Write + handler** : même modèle avec `post`, `put`, `patch` ; `@send`
   reste le déclencheur explicite.
-- **Theme** : `<sonic-theme background color font>` · `--sc-*` — skill `concorde-theme`
+- **Theme** : `<sonic-theme color font class="block bg-base">` · `--sc-*` — skill `concorde-theme`
 
 ## Migration Subscriber / sonic-fetch (piège fréquent)
 

package/ai/skills/concorde/SKILL.md

@@ -170,7 +170,7 @@ Avancés : `cache`, `blockUntilDone`, `keepAlive`, `addHTTPResponse`.
 
 Skill dédié : **`concorde-theme`**.
 
-`<sonic-theme background color font>` + variables CSS `--sc-*` (surfaces, sémantique, typo). Pas pour l’API.
+`<sonic-theme color font class="block bg-base">` + variables CSS `--sc-*` (surfaces, sémantique, typo). Pas pour l’API.
 
 ```typescript
 import "@supersoniks/concorde/theme";

package/ai/skills/concorde-theme/SKILL.md

@@ -8,37 +8,48 @@ description: >-
 
 `<sonic-theme>` définit la base visuelle Concorde. **Pas** pour l’API (`serviceURL` → scope, skill `concorde-scope`).
 
+Les composants ont un **rendu par défaut** sans override : fallbacks dans chaque composant + presets `light` / `dark`. Ne documenter que le **plus petit ensemble** de variables publiques `--sc-*` pour personnaliser un thème.
+
 ```typescript
 import "@supersoniks/concorde/theme";
 ```
 
 ```html
-<sonic-theme background color font>
+<sonic-theme color font class="block bg-base min-h-screen">
   …app…
 </sonic-theme>
 
 <!-- dark -->
-<sonic-theme theme="dark" background color font>…</sonic-theme>
+<sonic-theme theme="dark" color font class="block bg-base min-h-screen">…</sonic-theme>
 ```
 
 ## Attributs
 
 | Attribut | Rôle |
 |----------|------|
-| `background` | Fond page / surface (`--sc-base`) |
+| `class="bg-base block"` (Tailwind) | Fond page / surface (`--sc-base`) |
 | `color` | Couleur texte (`--sc-base-content`) |
 | `font` | Famille / graisse (`--sc-font-family-base`) |
-| `theme="light"` \| `"dark"` | Palette built-in |
+| *(omit)* \| `theme="custom"` | Défaut : tokens core + vos `--sc-*` ; pas de palette light/dark built-in |
+| `theme="light"` \| `"dark"` \| `"auto"` | Presets opt-in ; `auto` suit `prefers-color-scheme` |
+
+## Variables CSS essentielles (API publique)
+
+Override dans `:root`, sur `sonic-theme`, ou fichier CSS projet. **Ne pas** recopier les dérivées (`--sc-rounded-sm`, `--sc-btn-rounded`, …) : elles sont calculées par le thème à partir des primitives.
 
-## Variables CSS
+Convention : **sans suffixe `-content`** = couleur de **fond / surface / remplissage** ; **avec `-content`** = **texte et icônes** posés sur cette surface (boutons pleins, badges, etc.). Ne pas mélanger les deux rôles.
 
-Override dans `:root` ou fichier CSS projet :
+- **Surfaces neutres (fonds)** : `--sc-base`, `--sc-base-50` … `--sc-base-900`
+- **Texte sur surfaces neutres** : `--sc-base-content` (défaut UI, corps de page)
+- **Couleurs sémantiques (fonds)** : `--sc-primary`, `--sc-secondary` (si utilisé), `--sc-success`, `--sc-warning`, `--sc-danger`, `--sc-info`, `--sc-contrast`
+- **Texte sur fond sémantique** : `--sc-primary-content`, `--sc-secondary-content`, `--sc-success-content`, `--sc-warning-content`, `--sc-danger-content`, `--sc-info-content`, `--sc-contrast-content`
+- **Forme** : `--sc-rounded` (primitive unique pour les rayons)
+- **Typo** : `--sc-font-family-base`, `--sc-headings-font-family`, etc.
+- **Formulaires (optionnel, global)** : `--sc-border-width`, `--sc-form-height`, `--sc-input-bg`, `--sc-input-color`, `--sc-input-border-color`, états actifs `--sc-input-active-*`
 
-- Surfaces : `--sc-base`, `--sc-base-content`, `--sc-base-50` … `--sc-base-900`
-- Sémantique : `--sc-primary`, `--sc-success`, `--sc-warning`, `--sc-danger`, `--sc-info` (+ `-content`)
-- Forme : `--sc-rounded`, `--sc-btn-rounded`, `--sc-border-width`
-- Typo : `--sc-font-family-base`, `--sc-headings-font-family`
+Privé côté composants : `--sc_*`, `--sc-_color`, … — pas d’API par composant ni `::part()` sauf exceptions documentées.
 
+Doc utilisateur : `#docs/_getting-started/theming.md/theming`.  
 Doc composant : `node_modules/@supersoniks/concorde/src/core/components/ui/theme/`.
 
 Popovers, modals, toasts se montent sous le `<sonic-theme>` le plus proche.

package/build-infos.json

@@ -1 +1 @@
-{"date":1790844202}
+{"date":1791198231}