# Mystique Component Template

Standard format for documenting Mystique components. Each OOTB and custom component has its own `.md` file in the `components/` directory following this template.

## File Naming

- OOTB: `components/<alias>.md` (e.g., `components/fc.list.md`)
- Custom: same template, same directory (e.g., `components/custom.order-tracker.md`)

## Frontmatter

```yaml
---
alias: fc.list
aliases:
  - fc.list
  - shared.components.material.DynamicList
category: content
module: Core
---
```

### Frontmatter Fields

| Field | Required | Values |
|-------|----------|--------|
| `alias` | **Yes** | Primary component alias |
| `aliases` | **Yes** | All registered aliases (primary + legacy) |
| `category` | **Yes** | `page` / `layout` / `content` / `filter` / `field` / `action` |
| `module` | **Yes** | `Core` / `OMS` / `Store` / `Analytics` / `Returns` / `Custom` |

## Section Structure

```markdown
# <alias>

One-line description of what this component renders.

## When to Use
- User intent or UI need that maps to this component

## Key Props
| Prop | Type | Required | What it controls |
|------|------|----------|------------------|

## Data Binding
How it connects to data — dataSource path, query, template variables, or none.

## Descendants
Yes/No — what children it accepts and how they're rendered.

## Composition Patterns
- Typical parent/child pairings with other components

## Gotchas
- Known limitations or surprising behavior

## Validation Rules
IDs from /fluent-mystique-validate, if applicable.

## Manifest Example
```json
{ ... }
```
```

## How AI Uses This

1. **User describes a UI need** → grep `components/*.md` for matching capabilities
2. **Read matching component files** → understand props, data binding, composition
3. **Compose components** → use Composition Patterns to combine OOTB components
4. **Only if no OOTB match** → escalate to `/fluent-mystique-scaffold`

## Custom Component Analysis

When analyzing client custom components (from deployed manifests or SDK projects), create a new `.md` file in `components/` using this same template. Fill in from source code:
- `alias` from `ComponentRegistry.register()` call
- `category` from registration category parameter
- `module` = `Custom`
- Props from the React component's prop types/interface
- Data binding from `useData()` / `useQuery()` hook usage
