# Components reference This document is the **agent-and consumer-facing guide** for Magma's web components. It exists alongside, not instead of, the per-component docs: each component owns a Stencil-generated `readme.md` (props/events/slots/CSS vars) and a hand-authored `usage/` folder (description, patterns, anti-patterns). This guide tells you **which component to reach for**, **how to read the docs around it**, and **conventions that apply across the whole library**. If you only need to look up the props of a known component, skip this and read its `readme.md`. If you need to _pick_ a component, _use it correctly_, or _author new usage docs_, start here. ## Where component documentation lives Every component under [`projects/stencil/src/components//`](../projects/stencil/src/components/) exposes documentation in five files. Different files answer different questions - grep the right one: | File | Owner | Versioned | Answers | | ---------------------- | -------------- | --------------- | ------------------------------------------------------------------------------------------------- | | `usage/1. Description.md` | Authored | ✅ | What the component **is**, its semantic behavior, why it exists | | `usage/2. Pattern.md` | Authored | ✅ | How to use it **correctly** - recommended recipes with code | | `usage/3. Antipattern.md` | Authored | ✅ | How **not** to use it - paired `INCORRECT` / `CORRECT` snippets | | `readme.md` | Stencil (auto) | ✅ | What props, events, slots, methods, CSS vars exist (human-readable) | | `documentation.json` | Stencil (auto) | ❌ (local-only) | Structured JSON with full type metadata and cross-references; absent until `nx run stencil:build` | **Build flow.** Only the three `usage/*.md` files are hand-authored. On build, Stencil bundles them into `documentation.json` and injects the content into `readme.md`. As a consequence: never hand-edit `readme.md` or `documentation.json` - both are regenerated and your edits will be lost. To change what a component's docs say, edit the matching `usage/*.md`. Note that `documentation.json` is gitignored (`projects/stencil/.gitignore`) and only exists after a local build - do not rely on it being present in a fresh clone or when browsing the repo on GitHub. ### Which file should the agent read? Pick by task, not by preference: | You need… | Read | | --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | | Semantic intent ("what is this for, when do I use it?") | `usage/1. Description.md` (smallest, always present, hand-authored) | | Idiomatic examples / common mistakes | `usage/2. Pattern.md` and `usage/3. Antipattern.md` | | Props, events, slots, CSS custom properties | `readme.md` (always present, ~3-4× smaller than `documentation.json`) | | Typed prop value sets (what `tone` / `variant` / `size` accept) | [`components.d.ts`](../projects/stencil/src/components.d.ts) + [`type/*.ts`](../projects/stencil/src/type/) - the versioned source of truth | | Full type metadata, cross-references (for codemods / tooling) | `documentation.json` **if present**; otherwise build first or fall back to `components.d.ts` | Avoid loading `documentation.json` as a default - it's ~3-4× larger than `readme.md` and frequently absent. Reach for it only when you specifically need the structured type metadata it carries. ## The `usage/` contract Every component's `usage/` folder follows the same shape. Adhere to it when authoring new ones - agents and humans rely on the consistency. ### `1. Description.md` Plain prose. Sections in this order: 1. **Opening paragraph** - one or two sentences identifying the component and its role in the system. Reference the tag literally (e.g. ``). 2. **`## Semantic Behavior`** - bulleted list of _intrinsic_ behavior the component encapsulates (e.g. "Form Association", "Active State", "Disabled State"). Each bullet has a bold lead and a short explanation. Cover only behaviors that survive across themes, sizes, and variants. 3. **`## Properties & Visual Configurations`** - bulleted reference for each prop that drives appearance or semantics. Group sub-options with nested bullets. This is _not_ a duplicate of `readme.md`'s prop table - it explains the _intent_ and _combinations_, not the type signature. Avoid: code snippets, anti-patterns, "how to use" instructions. Those belong in the other two files. ### `2. Pattern.md` Numbered list (`## 1.`, `## 2.`, …) of correct usage recipes. Each entry: - A short title (`## 5. Navigation Link Style`). - One or two sentences on when/why to use this pattern. - One ` ```html ` (or ` ```css ` for styling patterns) code block. Order patterns from most-common to most-specialized. Include at least one styling-customization pattern showing the `--mds-*` CSS custom properties. Always reach for `label` props before slots when both are available. ### `3. Antipattern.md` Numbered list (`## 1.`, `## 2.`, …) of mistakes. Each entry: - A short title naming the mistake (`## 3. Do Not Nest Button Inside an Anchor Link`). - One or two sentences explaining _why_ it's wrong (accessibility, framework semantics, theme break, etc.). - A paired code block with both the `` and `` form. Prioritize anti-patterns that an AI agent or new contributor is statistically likely to commit (boolean attrs as strings, slot misuse, shadow-DOM piercing, raw HTML elements replacing components). ## Component reference One row per component. Group headings exist for scanability only - do **not** infer constraints from them. Find a component by intent (skim the right group, read the Intent column) or by HTML analogue (grep the Native analogue column when you'd otherwise reach for a native element). > **Native-analogue contract.** When the _Native analogue_ column is filled, the Magma component **preserves every native attribute with the same behavior** (`multiple`, `disabled`, `required`, `type`, `min`/`max`, `placeholder`, `name`, `autocomplete`, etc.). Magma adds UX affordances on top - theming, accessibility defaults, keyboard handling, slots for icons or badges, animations - but never alters or removes native semantics. If you'd write `` (text / email / etc.) | Single-line text input with validation, counter, and multiple input types. | | `mds-input-field` | - | Wrapper around an input that provides label, tip, and validation slots. | | `mds-input-select` | `` | Boolean on/off toggle or used as radio button (type="radio"). | | `mds-input-range` | `` | Slider for picking a numeric value between `min` and `max`. | | `mds-input-otp` | - | One-time-password / numeric-code entry, one digit per cell. | | `mds-input-date` | `` | Date picker with calendar overlay and ISO format handling. | | `mds-input-date-range` | - | Date range picker for selecting a start and end date. | | `mds-input-date-range-preselection` | - | Preset chooser for common date ranges (last week, last month, etc.). | | `mds-input-upload` | `` | File upload with drag-drop, preview, and progress support. | | `mds-input-tip` | - | Used internally, not meant for direct use. Hint / validation container shown alongside an input. | | `mds-input-tip-item` | - | Used internally, not meant for direct use. Single tip message inside `mds-input-tip`. | | `mds-calendar` | - | Visual calendar for date selection (without an input field). | | `mds-calendar-cell` | - | Used internally, not meant for direct use. Single day cell inside `mds-calendar`. | ### Actions | Component | Native analogue | Intent | | ---------------------- | ------------------ | ----------------------------------------------------------------- | | `mds-button` | `