@cascivo/mcp 0.2.0 → 0.3.4

package/dist/context/user.md

@@ -0,0 +1,100 @@
+# User
+
+**Category:** display  
+**Description:** Identity composite: an avatar with a name, description, and optional action slot
+
+## When to use
+
+- Showing a person with their name and a secondary line (email, role) next to an avatar
+- Identity rows inside menus, tables, navbars, and account switchers
+- A compact, labelled identity primitive too granular for a page-section block
+
+## When NOT to use
+
+- Just an image with no name/description — use Avatar directly
+- A full profile card with rich content — compose a Card instead
+
+## Anti-patterns
+
+### The name is the accessible identity label; an empty name leaves the avatar unlabelled
+
+**Bad:** `<User name="" avatarProps={{ src: "/jane.jpg" }} />`  
+**Good:** `<User name="Jane Doe" avatarProps={{ src: "/jane.jpg", alt: "Jane Doe" }} />`  
+**Why:** The name is the accessible identity label; an empty name leaves the avatar unlabelled
+
+## Related components
+
+- **Avatar** (contains): User wraps Avatar and forwards avatarProps to it
+- **AvatarGroup** (alternative): Use AvatarGroup to show several identities as an overlapping stack
+
+## Accessibility rationale
+
+The composite is a labelled group; the name provides the accessible identity and the avatar carries its own role="img"/alt — no redundant roles
+
+## Props
+
+| Name          | Type          | Required | Default | Description                        |
+| ------------- | ------------- | -------- | ------- | ---------------------------------- |
+| `name`        | `ReactNode`   | Yes      | —       | The user’s display name.           |
+| `description` | `ReactNode`   | No       | —       | Supporting description text.       |
+| `avatarProps` | `AvatarProps` | No       | —       | Forwarded to the composed <Avatar> |
+
+## Tokens
+
+- `--cascivo-color-text`
+- `--cascivo-color-text-muted`
+- `--cascivo-space-3`
+- `--cascivo-text-sm`
+- `--cascivo-text-xs`
+
+## Examples
+
+### Basic
+
+```jsx
+<User
+  name="Jane Doe"
+  description="jane@acme.com"
+  avatarProps={{ src: '/jane.jpg', alt: 'Jane Doe' }}
+/>
+```
+
+### With action
+
+```jsx
+<User name="Jane Doe" description="Admin">
+  <IconButton aria-label="More" />
+</User>
+```
+
+## Boundaries
+
+| Area        | Level    | Note                                                            |
+| ----------- | -------- | --------------------------------------------------------------- |
+| description | flexible | Any ReactNode — email, role, or a status line                   |
+| token names | strict   | Name and description colors must resolve to --cascivo-\* tokens |
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo User component (display). Identity composite: an avatar with a name, description, and optional action slot
+
+Architecture constraints — follow exactly:
+- Signals only (useSignal/useComputed/useSignalEffect from @cascivo/core). Never useState/useEffect/useContext/useReducer.
+- Style only through --cascivo-* custom properties. No Tailwind, no inline styles, no CSS-in-JS.
+- Responsive via @container queries on the canonical scale (30rem/40rem/64rem/80rem). Do not use global viewport @media breakpoints.
+- Visual states (hover/focus/active/disabled) via CSS pseudo-classes, not JS.
+- CSS logical properties only (RTL-safe).
+
+User is strictly bound to these tokens — use only these, do not invent token names:
+  --cascivo-color-text, --cascivo-color-text-muted, --cascivo-space-3, --cascivo-text-sm, --cascivo-text-xs
+
+Accessibility: role "group", WCAG 2.2-AA. Keep it AA.
+
+Do not change (strict): token names — Name and description colors must resolve to --cascivo-* tokens
+Flexible: description.
+
+Do not invent props, tokens, or global viewport media queries.
+```

package/dist/context/visually-hidden.md

@@ -0,0 +1,90 @@
+# VisuallyHidden
+
+**Category:** display  
+**Description:** Hides content visually while keeping it available to screen readers
+
+## When to use
+
+- Giving an icon-only control an accessible name without showing text
+- Adding screen-reader-only context that would be redundant visually
+- Providing off-screen labels for tables, links, or form controls
+
+## When NOT to use
+
+- Hiding content from everyone — use hidden or display:none
+- Temporarily hiding then revealing UI — use conditional rendering
+
+## Anti-patterns
+
+### VisuallyHidden keeps content in the accessibility tree — using it to hide noise pollutes screen-reader output
+
+**Bad:** `Wrapping decorative content in VisuallyHidden to "clean up" the layout`  
+**Good:** `aria-hidden on decorative elements; VisuallyHidden only for content screen readers need`  
+**Why:** VisuallyHidden keeps content in the accessibility tree — using it to hide noise pollutes screen-reader output
+
+## Related components
+
+- **SkipNav** (alternative): SkipNav uses a similar hidden-until-focused technique for skip links
+
+## Accessibility rationale
+
+Applies the standard clip technique so content stays in the DOM and accessibility tree while being painted off-screen — assistive tech reads it, sighted users do not see it
+
+## Props
+
+| Name       | Type        | Required | Default | Description                                               |
+| ---------- | ----------- | -------- | ------- | --------------------------------------------------------- |
+| `children` | `ReactNode` | Yes      | —       | Content announced by assistive technology but not painted |
+
+## Examples
+
+### Icon button label
+
+Gives an icon-only control an accessible name
+
+```jsx
+<button type="button">
+  <CloseIcon />
+  <VisuallyHidden>Close dialog</VisuallyHidden>
+</button>
+```
+
+### Table context
+
+```jsx
+<th>
+  Price <VisuallyHidden>(in euros)</VisuallyHidden>
+</th>
+```
+
+## Boundaries
+
+| Area                 | Level    | Note                                                    |
+| -------------------- | -------- | ------------------------------------------------------- |
+| children             | flexible | Any text/content meant for assistive tech               |
+| visibility technique | strict   | Must keep content in the a11y tree — never display:none |
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo VisuallyHidden component (display). Hides content visually while keeping it available to screen readers
+
+Architecture constraints — follow exactly:
+- Signals only (useSignal/useComputed/useSignalEffect from @cascivo/core). Never useState/useEffect/useContext/useReducer.
+- Style only through --cascivo-* custom properties. No Tailwind, no inline styles, no CSS-in-JS.
+- Responsive via @container queries on the canonical scale (30rem/40rem/64rem/80rem). Do not use global viewport @media breakpoints.
+- Visual states (hover/focus/active/disabled) via CSS pseudo-classes, not JS.
+- CSS logical properties only (RTL-safe).
+
+VisuallyHidden is strictly bound to these tokens — use only these, do not invent token names:
+  none declared
+
+Accessibility: role "none", WCAG 2.2-AA. Keep it AA.
+
+Do not change (strict): visibility technique — Must keep content in the a11y tree — never display:none
+Flexible: children.
+
+Do not invent props, tokens, or global viewport media queries.
+```