Document Callora design tokens and component visual specs in a CONTRIBUTING UI guide

[greatest0fallt1me]

Description

This is a UI/UX documentation issue. Callora defines a rich set of design tokens in src/index.css (--accent, --muted, --surface, --focus-ring, radii, transitions) and reusable components (Skeleton, EmptyState, Breadcrumb, CodeExample, ApiCard), but contributors have no reference for which token to use where or the visual spec of each component. New UI work drifts toward inline hex values (as seen in ApiDetailPage.tsx).

Requirements and Context

• Document the token palette (purpose, light/dark values) and usage rules.
• Document each shared component's props, states, and visual spec, with accessibility notes (focus, contrast, keyboard).
• State the rule that new UI must use tokens and shared components, not inline hex.
• Must be secure, tested, and documented
• Should be efficient and easy to review

Suggested Execution

1. Fork the repo and create a branch

   git checkout -b task/ui-design-tokens-doc

2. Implement changes
   • docs/UI-Design-System.md (new) covering tokens and component specs
   • Reference real files: src/index.css, src/components/*
3. Test and commit
   • Cross-check documented tokens against src/index.css
   • Have a reviewer follow the guide to style a sample element
   • Include notes in the PR

Example commit message

task: document design tokens and component visual specs

Acceptance Criteria

• All tokens in src/index.css are documented with purpose and theme values
• Each shared component has a documented spec with a11y notes
• The "tokens over inline hex" rule is stated
• Guide is linked from the README

Guidelines

• Keep the doc in sync with the actual token definitions
• Clear documentation and inline comments
• Timeframe: 96 hours