# Manner UI — full agent guide

Manner is a source-owned editorial React design system. It follows shadcn registry conventions: source is installed into the consumer project and remains editable there. Interactive primitives use Base UI where behavior needs a robust accessibility foundation.

Canonical references:

- Website: https://ui.myudak.com
- Repository: https://github.com/myudak/ui
- Machine manifest: https://ui.myudak.com/ai.json
- Registry index: https://ui.myudak.com/r/index.json
- Design rules: https://ui.myudak.com/DESIGN.md
- Agent workflow: https://ui.myudak.com/MANNER_AGENT.md

## Recommended workflow

1. Read this guide and `AGENTS.md` before changing interface code.
2. Inspect the consumer project's structure, `components.json`, and existing tokens.
3. Search installed Manner source and the registry index before creating a primitive.
4. Install the closest component or block through the shadcn CLI.
5. Adapt the copied source to the product task while preserving semantics and focus behavior.
6. Implement loading, empty, error, disabled, overflow, mobile, and reduced-motion states where relevant.
7. Run the consumer project's lint, typecheck, tests, and visual checks.
8. Report reused items, changed source, and intentional exceptions to the design rules.

## Installation

```bash
pnpm dlx shadcn@latest registry add @manner=https://ui.myudak.com/r/{name}.json
pnpm dlx shadcn@latest add @manner/button
pnpm dlx shadcn@latest add @manner/sidebar-01
pnpm dlx shadcn@latest add @manner/agent-rules
```

## Catalog

### UI components
- **button** — A Base UI-backed action with restrained Manner variants. · `pnpm dlx shadcn@latest add @manner/button`
- **input** — A semantic text input with visible focus and invalid states. · `pnpm dlx shadcn@latest add @manner/input`
- **textarea** — A readable multiline field with controlled resizing. · `pnpm dlx shadcn@latest add @manner/textarea`
- **field** — Label, description, and error primitives for form relationships. · `pnpm dlx shadcn@latest add @manner/field`
- **switch** — A Base UI-backed binary control with keyboard behavior. · `pnpm dlx shadcn@latest add @manner/switch`
- **select** — A Base UI-backed choice control with portal positioning and keyboard navigation. · `pnpm dlx shadcn@latest add @manner/select`
- **dialog** — A Base UI-backed modal with focus trapping and restoration. · `pnpm dlx shadcn@latest add @manner/dialog`
- **command** — A keyboard-first filtered command list. · `pnpm dlx shadcn@latest add @manner/command`
- **surface** — Semantic content grouping with default, inset, and raised tones. · `pnpm dlx shadcn@latest add @manner/surface`
- **section-heading** — Editorial hierarchy for meaningful sections. · `pnpm dlx shadcn@latest add @manner/section-heading`
- **note** — A restrained aside for contextual information. · `pnpm dlx shadcn@latest add @manner/note`
- **quote** — A quotation with strong reading rhythm and attribution. · `pnpm dlx shadcn@latest add @manner/quote`
- **timeline** — A compact semantic history for decisions and releases. · `pnpm dlx shadcn@latest add @manner/timeline`
- **metadata** — Dense supporting facts that remain calm and scannable. · `pnpm dlx shadcn@latest add @manner/metadata`
- **message** — Conversation content with authorship and optional actions. · `pnpm dlx shadcn@latest add @manner/message`
- **composer** — A flexible prompt input with keyboard submission. · `pnpm dlx shadcn@latest add @manner/composer`
- **reasoning** — Progressive disclosure for intermediate work. · `pnpm dlx shadcn@latest add @manner/reasoning`
- **tool-call** — Operational state for tool name, status, duration, and output. · `pnpm dlx shadcn@latest add @manner/tool-call`
- **sources** — Evidence links with origin context. · `pnpm dlx shadcn@latest add @manner/sources`
- **artifact** — A focused output surface connected to a conversation. · `pnpm dlx shadcn@latest add @manner/artifact`
- **checkbox** — An accessible independent selection control. · `pnpm dlx shadcn@latest add @manner/checkbox`
- **radio-group** — A mutually exclusive choice set with native keyboard behavior. · `pnpm dlx shadcn@latest add @manner/radio-group`
- **date-picker** — An accessible date input with a clear label. · `pnpm dlx shadcn@latest add @manner/date-picker`
- **file-upload** — A labeled upload target with selected-file feedback. · `pnpm dlx shadcn@latest add @manner/file-upload`
- **card** — A restrained bounded surface for meaningful grouping. · `pnpm dlx shadcn@latest add @manner/card`
- **drawer** — A spatially grounded side panel for secondary tasks. · `pnpm dlx shadcn@latest add @manner/drawer`
- **tooltip** — A short accessible label for compact controls. · `pnpm dlx shadcn@latest add @manner/tooltip`
- **tabs** — Keyboard-friendly related view switching. · `pnpm dlx shadcn@latest add @manner/tabs`
- **breadcrumb** — A semantic location trail for shallow hierarchies. · `pnpm dlx shadcn@latest add @manner/breadcrumb`
- **pagination** — Navigation through ordered result pages. · `pnpm dlx shadcn@latest add @manner/pagination`
- **stepper** — Progress through a finite multi-step flow. · `pnpm dlx shadcn@latest add @manner/stepper`
- **alert** — A semantic status message with calm hierarchy. · `pnpm dlx shadcn@latest add @manner/alert`
- **progress** — A labeled semantic completion meter. · `pnpm dlx shadcn@latest add @manner/progress`
- **skeleton** — A reduced-motion loading placeholder. · `pnpm dlx shadcn@latest add @manner/skeleton`
- **empty-state** — An empty result explanation with a useful next action. · `pnpm dlx shadcn@latest add @manner/empty-state`
### Blocks
- **login-01** — A focused sign-in composition with product context. · `pnpm dlx shadcn@latest add @manner/login-01`
- **sidebar-01** — A content-first shell with compact navigation. · `pnpm dlx shadcn@latest add @manner/sidebar-01`
- **settings-01** — Section navigation, accessible controls, and explicit save state. · `pnpm dlx shadcn@latest add @manner/settings-01`
- **reader-01** — Outline navigation, long-form reading, and margin notes. · `pnpm dlx shadcn@latest add @manner/reader-01`
- **ai-workspace-01** — Messages, composer, and a responsive artifact panel. · `pnpm dlx shadcn@latest add @manner/ai-workspace-01`
- **leaderboard-01** — Ranked data with methodology context and responsive overflow. · `pnpm dlx shadcn@latest add @manner/leaderboard-01`
### Agent files
- **agent-rules** — Installs Manner design constraints and agent workflow at the consumer project root. · `pnpm dlx shadcn@latest add @manner/agent-rules`

## Visual language

# Manner Interface Rules

Manner is a warm, editorial interface system for thoughtful software.
It is independent and is not affiliated with Anthropic or Claude.

## Product feeling

Interfaces should feel literate, calm, curious, competent, warm, and slightly unconventional. They should never feel corporate-luxury, faux-vintage, overly cute, or generically AI-generated.

## Non-negotiable rules

- Use semantic design tokens. Do not add arbitrary color values inside components.
- Search existing components and blocks before creating a new primitive.
- Use visible surfaces only when grouping requires a container.
- Do not wrap every section, statistic, or list item in a card.
- Use serif typography only for major titles, quotes, selected numbers, and editorial emphasis.
- Use sans-serif typography for controls, forms, tables, and dense reading.
- Use monospace for metadata, code, keyboard hints, timestamps, and system state.
- Use thin borders and tonal contrast before shadows.
- Keep control radii small to medium. Pills are reserved for status, tags, and compact filters.
- Motion must explain state, continuity, hierarchy, or origin.
- Every interaction needs visible keyboard focus and an accessible name.
- Design mobile layouts intentionally. Do not merely shrink desktop grids.
- Respect `prefers-reduced-motion`.

## Semantic tokens

Use `canvas`, `surface`, `surface-raised`, `surface-inset`, `ink`, `ink-secondary`, `ink-muted`, `accent`, `accent-soft`, `border-subtle`, `border`, `border-strong`, `focus`, `success`, `warning`, `danger`, and `info` instead of component-specific colors.

## Typography

- Display: Fraunces Variable, approximately weight 420.
- Interface and body: Geist or Inter Variable.
- Code and metadata: IBM Plex Mono.
- Keep long-form body measure between 58 and 72 characters.
- Use line-height 1.55–1.75 for prose.
- Never use serif for tiny labels, dense tables, or code-adjacent UI.

## Shape and elevation

- xs radius: 4px
- sm radius: 6px
- md radius: 10px
- lg radius: 14px
- xl radius: 20px, only for major canvases

Most content grouping uses no shadow. Menus may use lift-1. Dialogs may use lift-2. Do not place giant blurred shadows behind normal cards.

## Motion vocabulary

- `enter-soft`
- `exit-soft`
- `reveal-line`
- `shift-active`
- `expand-panel`
- `swap-content`
- `press-control`

Micro-interactions use 100–160ms. Menus and overlays use 140–220ms. Panels and layout changes use 180–300ms. Avoid bounce and decorative zoom by default.

## Responsive behavior

Validate at 360, 390, 768, 1024, and 1440 pixels. Sidebars become sheets, tabs, or compact selectors. Multi-panel AI interfaces show one primary panel at a time. Keep essential actions available without hover. Preserve readable measure.

## Accessibility

Target WCAG 2.2 AA with full keyboard operation, visible focus, accessible names, correct field relationships, non-color state indicators, logical focus order, dialog focus restoration, reduced motion, and 400% reflow.

## Avoid

- arbitrary colors inside components
- generic gradients and gradient text
- glassmorphism for ordinary surfaces
- giant centered hero followed by three generic cards
- nested card inside card inside card
- every control rendered as a pill
- decorative motion that delays interaction
- low-contrast beige-on-beige text
- fixed-height content that clips user text or localization
- icon-only actions without labels

## Agent workflow

1. Inspect the existing application structure, `components.json`, and tokens.
2. Reuse Manner components before creating new primitives. Add missing source with `pnpm dlx shadcn@latest add @manner/<name>`.
3. Choose a composition based on the user task, not visual novelty.
4. Implement loading, empty, error, disabled, and overflow states where applicable.
5. Verify keyboard use, visible focus, reduced motion, and mobile transformation.
6. Explain any intentional exception to these rules.
7. Update documentation and tests when component behavior changes.

Install the rules and a component with:

```sh
pnpm dlx shadcn@latest registry add @manner=https://ui.myudak.com/r/{name}.json
pnpm dlx shadcn@latest add @manner/agent-rules
pnpm dlx shadcn@latest add @manner/button
```

## Definition of done

A stable component has semantic tokens, light and dark modes, keyboard tests, accessible state, visible focus, reduced motion, mobile behavior, long-content coverage, relevant loading/error/empty states, documentation, and real usage in at least one application composition.


## Source and registry rules

- Use semantic CSS variables rather than component-specific color literals.
- Prefer existing Manner components and composition blocks over new primitives.
- Keep source imports explicit and local after installation.
- Do not claim Manner is affiliated with Anthropic, Claude, shadcn, or Base UI.
- If a component must diverge, document why and keep its accessibility behavior intact.