Vois Patterns Skill

You are building the structure of pages and containers for a design system. This skill defines the architectural decisions that come before implementation (tokens, components, styling).

Read this skill first. After you determine structure here, read vois-tokens for implementation details (spacing, typography, components, tokens).

This skill routes to righter skill for all microcopy (button labels, error messages, field descriptions, helper text). Don’t guess at words—follow the righter skill.

Before You Write Anything

1. What is the user trying to accomplish? (Dashboard overview? Edit a record? Confirm an action?)

2. Pick the container type from the decision tree below.

3. Read the matching reference file for full template rules.

4. Call record_pattern_decision once you have picked a path. Do this before writing any code.

   Tool: record_pattern_decision
   Arguments:
     pathId: <one of the path IDs listed in the decision tree below>
     confidence: <0.0–1.0 — how clearly the UI fits this path>
     reasoning: <one sentence on why you chose this path>

   If no path fits well (confidence below 0.6), call report_pattern_gap instead of forcing a match:

   Tool: report_pattern_gap
   Arguments:
     description: <what the UI needs to do>
     closestPathId: <the closest match even if it doesn't fit>
     gapDescription: <what the templates don't cover>

5. For every word that appears in UI, check righter skill. See references/microcopy-routing.md for the full list of what counts as copy.

6. Then read vois-tokens for implementation (tokens, spacing, components).

Decision Tree: What Container Type Should I Build?

START: What is the user trying to accomplish?

├─ PATH A: Manage settings or account preferences
│  └─ → read references/settings-pages.md
│     ├─ IF: 2–3 sections only      → [PATH-A-DEPTH-SHALLOW]
│     └─ IF: 4+ sections            → [PATH-A-DEPTH-DEEP]
│
├─ PATH B: View, filter, and act on a list of items
│  └─ → read references/table-list.md                       [PATH-B]
│
├─ PATH C: Create a new item OR edit an existing item
│  └─ → read references/forms.md
│     ├─ IF: 1–6 fields             → [PATH-C-SIMPLE]
│     ├─ IF: 7–15 fields            → [PATH-C-MEDIUM]
│     └─ IF: 15+ fields / complex   → [PATH-C-COMPLEX]
│
├─ PATH D: Quick input, confirmation, or selection
│  └─ → read references/dialogs-and-action-sheets.md         [PATH-D]
│
└─ PATH E: View details of a single item (read-only or view state)
   └─ → read references/detail-pages.md                      [PATH-E]

Read only the one reference file that matches the path you picked. Each template file is self-contained.

Reference Files

Spacing Rules (Quick Reference)

These are implemented via vois-tokens; listed here for context.

• 24px vertical: heading ↔ body text
• 24px horizontal: between two input fields
• 40px vertical: body content ↔ primary action button
• 20px horizontal: between primary/secondary buttons (bottom right anchored)
• Use gap tokens on container div instead of margin-bottom on elements

For exact Tailwind class names and token values, see vois-tokens.

Quick Checklist Before Implementation

• Container type selected (settings / table / form / dialog / detail)
• record_pattern_decision called with pathId and confidence
• Page structure sketched (what sections, what’s visible, what’s hidden by role)
• Permissions applied (hide/disable rules — see references/permissions-and-conditional-logic.md)
• All copy routed to righter skill and reviewed
• Ready to read vois-tokens for tokens, spacing, components
• Mobile breakpoint behavior defined (action sheets vs dialogs, sidebar vs hamburger, etc.)

Relationship to Other Skills

This skill ↔ vois-tokens:

• Read this first (what to build)
• Then read vois-tokens (how to code it correctly)
• vois-tokens handles tokens, spacing, components, animation, accessibility
• This skill handles structural decisions and microcopy routing

This skill ↔ vois-components:

• After picking a container type here, read vois-components to select specific components
• vois-components resolves ambiguous pairs — Dialog vs Drawer, Toast vs Banner, Select vs Combobox
• Always call record_component_choice after selecting; do not skip it

This skill ↔ righter skill:

• Every word in UI comes from righter
• This skill tells you which container type
• Righter skill tells you what words go in that container
• Always check righter for: button labels, error messages, field descriptions, status copy, confirmations