neomithril-component-authoring

name	neomithril-component-authoring
description	Use when adding or refactoring shared UI components in neomithril-ui so they follow the repository design system, neumorphic rules, token contract, CSS module patterns, surface-vs-semantic composition model, and required docs/story/manifest updates.

Neomithril Component Authoring

Use this skill for public UI component work in neomithril-ui.

Load These References

• Always read ../../../docs/design-manifesto.md.
• Always read references/design-principles.md.
• Always read references/neumorphism-rules.md.
• Read references/component-integration-checklist.md before finishing the task.

Workflow

1. Classify the component before editing.
   • surface primitive: layout/material container such as Card, Dialog, Toolbar, Hero, MarkdownEditor
   • semantic feedback: Notice-style warning, error, success, info messaging
   • interactive control: button, toggle, input, slider, tabs, segmented control
   • display primitive: badge, icon, text, avatar, metric, status chip
2. Keep semantic meaning out of large structural shells.
   • Surface primitives should normally expose surface="neutral" | "muted" instead of semantic body fills.
   • Compact support surfaces such as tooltips and popovers should also stay neutral or muted unless they are explicitly semantic feedback primitives.
   • If the request sounds like "error state", "warning panel", "success block", or "toast body", prefer a dedicated feedback component or nested semantic accents.
3. Build the API around tokens and composition.
   • Prefer variant presets plus a small set of token-backed overrides.
   • If depth is independently configurable, expose it as neoDepth instead of inventing variant="neoRaised" / variant="neoInset" values.
   • Do not encode clickable or tactile affordance inside semantic tone; use dedicated props such as interactive, clickable, pressed, or component-specific state.
   • Prefer compound subcomponents when block hierarchy matters.
   • Reuse existing types from src/design/tokens, src/layout/card, and src/primitives when possible.
4. Author CSS with local variables and engine hooks.
   • Use CSS Modules.
   • Derive spacing, radius, typography, and color from tokens or generated theme variables.
   • Use data-neo-surface and data-tone only when the component is intentionally participating in the shared neo engine.
   • Avoid hard-coded shadows, saturated large-area fills, or one-off hex values unless they are impossible to express through tokens.
5. Teach the component through examples.
   • Add or update Storybook stories that show recommended composition, not just raw prop playgrounds.
   • Include a "do/don't" or real-use-case story when misuse is likely.
6. Close the public contract.
   • Update local README.md, src/index.ts, slice indexes, src/manifest/libraryManifest.ts, and consumer-facing docs when public behavior changes.
   • If the change is architectural or breaking, update the decision log and agent guidance.
7. Run a manifesto review before closing.
   • Check the result against docs/design-manifesto.md.
   • If the change intentionally breaks a manifesto rule, document the reason in the relevant README, story, or decision entry.

Repository Guardrails

• Keep components app-agnostic.
• Prefer root exports for public components.
• Preserve react / react-dom peer-only expectations.
• Do not leave stories, manifest entries, or docs teaching an outdated API.

Validation

Run the relevant checks from the integration checklist. For public component work, that usually includes pnpm typecheck, pnpm test -- --project unit, pnpm lint, pnpm build, pnpm build-storybook, and pnpm test:storybook.

Validation is not complete until the component also passes a short manifesto review covering:

• correct component role classification
• surface-vs-semantic placement
• token/theme integration
• light/dark readability
• Storybook guidance quality