ai-playbook 1.0.0

package/roles/design-architect/skill-map.md

@@ -0,0 +1,42 @@
+# Skill Map for Design Architect
+
+Use this map to select the smallest set of role topic folders and skills needed
+for a design architecture task.
+
+## Routing Matrix
+
+| Task type | Required role packets | Supporting skills or context | Output |
+| --- | --- | --- | --- |
+| Design system creation | `design-system/`, `component-library/`, `accessibility/`, `figma/` | `skills/design-architecture/skill.md` | Token, component, pattern, governance, and adoption plan. |
+| Component specification | `component-library/`, `accessibility/`, `figma/` | `roles/software-developer/frontend/components/` | Component anatomy, variants, states, behavior, and acceptance criteria. |
+| Screen or flow design | `ux/`, `ui/`, `wireframes/`, `usability/` | Product or project context | Flow, layout, hierarchy, state model, and validation notes. |
+| Responsive design | `responsive/`, `ui/`, `ux/`, `accessibility/` | Frontend implementation guidance | Breakpoints, adaptive behavior, input-mode notes, and QA checklist. |
+| Accessibility audit | `accessibility/`, `ui/`, `component-library/` | Frontend accessibility guidance | Findings, fixes, WCAG mapping, and verification plan. |
+| Wireframing | `wireframes/`, `ux/`, `usability/` | Research or product context | Low-fidelity layouts, flow options, assumptions, and open questions. |
+| Figma organization | `figma/`, `design-system/`, `component-library/` | Existing Figma or design system conventions | Page structure, naming, component organization, and handoff rules. |
+| Usability validation | `usability/`, `ux/` | Analytics, support, research, or QA context | Test plan, task scenarios, findings format, and iteration plan. |
+| Visual polish review | `ui/`, `accessibility/`, `responsive/` | Brand and frontend context | Prioritized design critique and specific corrections. |
+| Developer handoff | `figma/`, `component-library/`, `responsive/`, `accessibility/` | `roles/software-developer/frontend/` | Annotated specs, acceptance criteria, states, and implementation risks. |
+
+## Proficiency Areas
+
+| Domain | What strong performance looks like | Reference |
+| --- | --- | --- |
+| Design systems | Defines foundations, components, tokens, documentation, and governance that scale across teams. | `design-system/` |
+| Interaction design | Creates flows that expose the right decisions at the right time and handle edge states. | `ux/` |
+| Visual design | Uses hierarchy, typography, spacing, color, and motion to support comprehension. | `ui/` |
+| Accessibility | Designs for WCAG AA, keyboard use, screen readers, contrast, zoom, and reduced motion. | `accessibility/` |
+| Responsive design | Adapts layouts and interactions across size, density, and input mode. | `responsive/` |
+| Component architecture | Defines reusable components with clear variants, states, content rules, and behavior. | `component-library/` |
+| Research and validation | Selects appropriate evidence methods and translates findings into design changes. | `usability/` |
+| Handoff | Documents specs so engineering can build without guessing. | `figma/` |
+
+## Routing Rules
+
+- Load only packets relevant to the surface and deliverable.
+- Prefer existing system patterns over creating new patterns.
+- Use the design architecture skill as the competency source for all design work.
+- Use frontend role guidance when the work will be implemented in a web or app
+  codebase.
+- If a referenced project design system exists, treat it as the source of truth
+  unless the task is explicitly to change it.

package/roles/design-architect/triggers.md

@@ -0,0 +1,110 @@
+# Design Architect Triggers
+
+Use this role when a request includes any of the following signals.
+
+## Product Experience Design
+
+Trigger examples:
+
+- "Design this screen"
+- "Improve the UX"
+- "Make this dashboard easier to use"
+- "Create a flow for onboarding"
+- "Review this user journey"
+
+Immediate response:
+
+- Clarify user goal and success criteria.
+- Load `ux/`, `ui/`, `usability/`, and relevant platform guidance.
+- Define flow, hierarchy, states, and validation plan.
+
+## Design System or Component Library
+
+Trigger examples:
+
+- "Create a design system"
+- "Standardize components"
+- "Define tokens"
+- "Document component variants"
+- "Clean up inconsistent UI patterns"
+
+Immediate response:
+
+- Load `design-system/` and `component-library/`.
+- Inventory existing patterns before proposing additions.
+- Define tokens, component anatomy, states, usage rules, and governance.
+
+## Accessibility Review
+
+Trigger examples:
+
+- "Check accessibility"
+- "Make this WCAG compliant"
+- "Design for keyboard and screen readers"
+- "Improve contrast"
+
+Immediate response:
+
+- Load `accessibility/`.
+- Evaluate perceivable, operable, understandable, and robust requirements.
+- Produce specific fixes and verification steps.
+
+## Responsive or Cross-Device Design
+
+Trigger examples:
+
+- "Make this responsive"
+- "Design mobile and desktop layouts"
+- "Fix tablet layout"
+- "Support touch and keyboard"
+
+Immediate response:
+
+- Load `responsive/`, plus `ui/` and `ux/` when layout or flow changes.
+- Define content-driven breakpoints, layout behavior, and input-mode differences.
+
+## Wireframes and Early Concepts
+
+Trigger examples:
+
+- "Sketch the flow"
+- "Create wireframes"
+- "Explore layout options"
+- "Show low-fidelity structure"
+
+Immediate response:
+
+- Load `wireframes/` and `ux/`.
+- Prioritize content, actions, and decisions over visual styling.
+- Present alternatives with trade-offs.
+
+## Figma Handoff or File Organization
+
+Trigger examples:
+
+- "Organize the Figma file"
+- "Prepare handoff"
+- "Document specs"
+- "Create components in Figma"
+
+Immediate response:
+
+- Load `figma/`, `component-library/`, and relevant design-system guidance.
+- Define naming, page structure, component sets, variants, annotations, and
+  developer handoff notes.
+
+## Design Review
+
+Trigger examples:
+
+- "Review this mockup"
+- "Critique this UI"
+- "What is wrong with this design?"
+- "Polish this screen"
+
+Immediate response:
+
+- Load `checklists.md` and relevant topic folders.
+- Lead with highest-risk findings.
+- Tie feedback to usability, accessibility, consistency, feasibility, or visual
+  hierarchy.

package/roles/design-architect/ui/README.md

@@ -0,0 +1,36 @@
+# UI Design
+
+UI design defines the visual structure of an interface: hierarchy, layout,
+typography, color, spacing, iconography, motion, and state presentation.
+
+## Scope
+
+- Visual hierarchy and composition.
+- Typography and readability.
+- Color, contrast, and semantic status.
+- Layout, spacing, alignment, and density.
+- Icons, imagery, and motion.
+- Visual polish for production interfaces.
+
+## Standards
+
+- Hierarchy should make the primary action and most important information clear.
+- Typography should match content density and reading context.
+- Spacing should follow a repeatable system.
+- Color should support meaning, not carry it alone.
+- Motion should clarify state or relationship.
+- Visual choices should fit product context and brand.
+
+## Deliverables
+
+- Visual design review.
+- Layout and hierarchy recommendations.
+- Token or style guidance.
+- State and polish notes.
+- Implementation-ready UI annotations.
+
+## Related Guidance
+
+- `../design-system/` for tokens and foundations.
+- `../accessibility/` for contrast and inclusive visual states.
+- `../responsive/` for layout adaptation.

package/roles/design-architect/ui/checklists.md

@@ -0,0 +1,29 @@
+# UI Design Checklists
+
+## Hierarchy Checklist
+
+- [ ] Primary content is visually dominant.
+- [ ] Primary action is easy to identify.
+- [ ] Secondary actions are lower emphasis.
+- [ ] Related items are grouped.
+- [ ] Page structure supports scanning.
+- [ ] Headings and labels are specific.
+
+## Visual System Checklist
+
+- [ ] Typography scale is consistent.
+- [ ] Line lengths and line heights are readable.
+- [ ] Spacing follows a repeatable rhythm.
+- [ ] Alignment is intentional.
+- [ ] Color usage has semantic purpose.
+- [ ] Iconography is consistent and labeled when needed.
+- [ ] Motion is purposeful and restrained.
+
+## State Checklist
+
+- [ ] Empty states are helpful.
+- [ ] Loading states preserve layout where possible.
+- [ ] Error states explain recovery.
+- [ ] Success states confirm completion.
+- [ ] Disabled states explain unavailability when needed.
+- [ ] Selected and active states are visually distinct.

package/roles/design-architect/ui/examples.md

@@ -0,0 +1,28 @@
+# UI Design Examples
+
+## Hierarchy Fix
+
+```text
+Issue:
+Three buttons in the header use the same visual weight.
+
+Fix:
+- Keep the main task as the only primary button.
+- Convert secondary actions to lower-emphasis buttons.
+- Move rare actions into an overflow menu.
+```
+
+## Typography Note
+
+```text
+Dashboard cards:
+- Title: compact label, medium weight.
+- Metric: largest text in card.
+- Supporting context: muted body text.
+- Trend: semantic color plus icon and text.
+```
+
+## Loading State
+
+Prefer skeletons when layout is known and loading is brief. Use progress text
+when the operation may take long enough that users need reassurance or context.

package/roles/design-architect/usability/README.md

@@ -0,0 +1,34 @@
+# Usability
+
+Usability guidance evaluates whether users can complete real tasks accurately,
+efficiently, and confidently.
+
+## Scope
+
+- Task success and friction analysis.
+- Usability testing plans.
+- Heuristic review.
+- Analytics and support signal interpretation.
+- Iteration plans based on evidence.
+
+## Standards
+
+- Define the user task before judging the interface.
+- Separate observed behavior from interpretation.
+- Prioritize problems by frequency, severity, and business impact.
+- Validate high-risk flows before investing in polish.
+- Convert findings into specific design changes.
+
+## Deliverables
+
+- Usability review.
+- Test plan and task scenarios.
+- Findings summary.
+- Prioritized recommendations.
+- Follow-up validation plan.
+
+## Related Guidance
+
+- `../ux/` for journeys, flows, and information architecture.
+- `../ui/` for visual clarity.
+- `../accessibility/` for inclusive usability.

package/roles/design-architect/usability/checklists.md

@@ -0,0 +1,28 @@
+# Usability Checklists
+
+## Review Checklist
+
+- [ ] Primary user task is stated.
+- [ ] Entry point and next step are obvious.
+- [ ] Required information is available at the decision point.
+- [ ] Users can recover from mistakes.
+- [ ] Labels match user language.
+- [ ] Feedback confirms important actions.
+- [ ] The interface avoids unnecessary choices.
+
+## Test Plan Checklist
+
+- [ ] Research question is clear.
+- [ ] Participant profile matches target users.
+- [ ] Tasks are realistic and unbiased.
+- [ ] Success criteria are measurable.
+- [ ] Moderator notes avoid leading language.
+- [ ] Findings template separates observations from recommendations.
+
+## Findings Checklist
+
+- [ ] Findings include evidence.
+- [ ] Severity is assigned.
+- [ ] Recommendations are specific.
+- [ ] Open questions are tracked.
+- [ ] Follow-up validation is planned for high-risk changes.

package/roles/design-architect/usability/examples.md

@@ -0,0 +1,31 @@
+# Usability Examples
+
+## Task Scenario
+
+```text
+You manage a project with five teammates. Invite a new teammate as a viewer and
+confirm they were added successfully.
+```
+
+## Finding Format
+
+```text
+Finding:
+Participants did not notice the role selector before sending the invite.
+
+Evidence:
+4 of 6 participants submitted the default role unintentionally.
+
+Impact:
+New members may receive incorrect access.
+
+Recommendation:
+Move role selection directly next to the email field and include a short helper
+text explaining the default.
+```
+
+## Severity Guide
+
+- High: prevents task completion or creates serious risk.
+- Medium: causes delay, confusion, or likely support burden.
+- Low: creates minor friction or polish issue.

package/roles/design-architect/ux/README.md

@@ -0,0 +1,36 @@
+# UX Design
+
+UX design defines the structure of the user's experience: goals, flows,
+information architecture, navigation, decisions, feedback, and recovery.
+
+## Scope
+
+- User journeys and task flows.
+- Information architecture and navigation.
+- Interaction models and progressive disclosure.
+- Form and decision design.
+- State, error, and recovery paths.
+
+## Standards
+
+- Start with the user's job and context.
+- Make the next step obvious.
+- Reveal complexity only when needed.
+- Keep language concrete and task-oriented.
+- Design recovery paths, not only happy paths.
+- Align flows with product metrics and user outcomes.
+
+## Deliverables
+
+- Journey map.
+- User flow.
+- Information architecture.
+- Interaction model.
+- State model.
+- UX review findings.
+
+## Related Guidance
+
+- `../wireframes/` for low-fidelity structure.
+- `../usability/` for validation.
+- `../ui/` for visual hierarchy.

package/roles/design-architect/ux/checklists.md

@@ -0,0 +1,28 @@
+# UX Design Checklists
+
+## Flow Checklist
+
+- [ ] User goal is clear.
+- [ ] Entry points are defined.
+- [ ] Primary path has minimal avoidable steps.
+- [ ] Decision points include enough context.
+- [ ] Confirmation and feedback are clear.
+- [ ] Recovery paths exist for errors and cancellations.
+- [ ] Exit points are intentional.
+
+## Information Architecture Checklist
+
+- [ ] Navigation labels match user expectations.
+- [ ] Content is grouped by task or mental model.
+- [ ] Important information is not buried.
+- [ ] Hierarchy supports scanning.
+- [ ] Search, filtering, or sorting exists when content volume requires it.
+- [ ] Future content growth is considered.
+
+## Interaction Checklist
+
+- [ ] Controls have clear affordances.
+- [ ] Progressive disclosure reduces overload.
+- [ ] Destructive actions are protected.
+- [ ] System feedback appears near the relevant action.
+- [ ] Permissions and unavailable actions are explained.

package/roles/design-architect/ux/examples.md

@@ -0,0 +1,37 @@
+# UX Design Examples
+
+## User Flow
+
+```text
+Start: User receives invitation link.
+1. Open invitation.
+2. Review workspace name and invited role.
+3. Sign in or create account.
+4. Accept invitation.
+5. Land in workspace with welcome confirmation.
+
+Failure states:
+- Expired invite.
+- Already accepted invite.
+- User lacks allowed email domain.
+```
+
+## Progressive Disclosure
+
+```text
+Basic settings:
+- Project name
+- Visibility
+- Default role
+
+Advanced settings:
+- Domain restrictions
+- SCIM sync
+- Audit retention
+```
+
+## Navigation Recommendation
+
+Group settings by user intent instead of implementation area. "Members" and
+"Billing" are clearer than "Accounts" and "Subscriptions" if that is how users
+describe the tasks.

package/roles/design-architect/wireframes/README.md

@@ -0,0 +1,34 @@
+# Wireframes
+
+Wireframes explore structure, content priority, user flow, and interaction
+before visual design details are finalized.
+
+## Scope
+
+- Low-fidelity screen layouts.
+- Flow exploration.
+- Content hierarchy.
+- Navigation and action placement.
+- State and edge-case planning.
+
+## Standards
+
+- Keep wireframes focused on structure and decisions.
+- Use real or representative content where possible.
+- Include states and alternate paths.
+- Explore multiple options when the structure is uncertain.
+- Annotate assumptions and trade-offs.
+
+## Deliverables
+
+- Low-fidelity screen set.
+- Flow map.
+- Layout alternatives.
+- Annotation notes.
+- Open questions and validation plan.
+
+## Related Guidance
+
+- `../ux/` for flow and information architecture.
+- `../ui/` for later visual treatment.
+- `../usability/` for testing plans.

package/roles/design-architect/wireframes/checklists.md

@@ -0,0 +1,25 @@
+# Wireframe Checklists
+
+## Structure Checklist
+
+- [ ] Primary task is represented.
+- [ ] Content priority is clear.
+- [ ] Main action and secondary actions are placed.
+- [ ] Navigation context is visible.
+- [ ] Empty, loading, error, and success states are considered.
+- [ ] Layout supports expected content length.
+
+## Exploration Checklist
+
+- [ ] More than one option is explored when the pattern is uncertain.
+- [ ] Trade-offs are documented.
+- [ ] Assumptions are marked.
+- [ ] Open questions are listed.
+- [ ] Validation plan matches the risk.
+
+## Handoff Checklist
+
+- [ ] Wireframe purpose and fidelity are clear.
+- [ ] Notes explain behavior.
+- [ ] Visual details are not mistaken for final design.
+- [ ] Next design step is identified.

package/roles/design-architect/wireframes/examples.md

@@ -0,0 +1,32 @@
+# Wireframe Examples
+
+## Layout Alternative Notes
+
+```text
+Option A: Sidebar filters
+Best for repeated analysis and large result sets.
+Risk: Takes horizontal space on smaller screens.
+
+Option B: Top filter bar
+Best for compact workflows with common filters.
+Risk: Advanced filters may become hidden or crowded.
+```
+
+## State Coverage
+
+```text
+Results screen:
+- Loading skeleton
+- Empty before search
+- Empty after search
+- Error with retry
+- Results with pagination
+- Results with selected filters
+```
+
+## Wireframe Annotation
+
+```text
+Primary action is intentionally below the summary because users should review
+the generated changes before applying them.
+```

package/roles/design-architect/workflow.md

@@ -0,0 +1,80 @@
+# Design Architect Workflow
+
+```text
+Receive Request
+    |
+Clarify User, Goal, Constraints
+    |
+Load Context and Topic Packets
+    |
+Audit Existing Patterns
+    |
+Define Flow and Information Architecture
+    |
+Create Structure and States
+    |
+Apply Visual and System Rules
+    |
+Validate Accessibility, Usability, Responsiveness
+    |
+Document Handoff
+    |
+Report Outcome and Open Questions
+```
+
+## 1. Intake
+
+- Identify the product surface, audience, workflow, and requester goal.
+- Confirm the deliverable: critique, wireframe, design system spec, prototype
+  plan, Figma guidance, implementation notes, or review.
+- Capture hard constraints such as platform, timeline, existing components,
+  brand rules, content availability, and engineering limits.
+
+## 2. Context Loading
+
+- Load `role.md`, `skill-map.md`, and `checklists.md`.
+- Load relevant topic folders only.
+- Load `skills/design-architecture/skill.md`.
+- Load frontend implementation guidance when the design will be built in code.
+
+## 3. Existing Pattern Audit
+
+- Find current components, tokens, layouts, routes, and interaction conventions.
+- Identify reusable patterns before proposing new ones.
+- Note inconsistencies, accessibility risks, and missing states.
+
+## 4. Structure First
+
+- Define the user journey and information hierarchy.
+- Choose navigation, layout, grouping, and progressive disclosure patterns.
+- Specify primary, secondary, and destructive actions.
+- Include empty, loading, error, success, disabled, and edge states.
+
+## 5. System and Visual Design
+
+- Map designs to tokens, components, variants, and patterns.
+- Define spacing, typography, color, iconography, and motion purposefully.
+- Keep visual choices aligned with brand, context, and user task intensity.
+
+## 6. Validation
+
+- Run the relevant checklist gates.
+- Check accessibility, usability, responsive behavior, content variation, and
+  technical feasibility.
+- Identify what needs user testing, analytics review, or engineering spike work.
+
+## 7. Handoff
+
+- Document component mapping, tokens, layout rules, breakpoints, states,
+  interactions, copy notes, and acceptance criteria.
+- Highlight changes from current behavior.
+- List risks, assumptions, open questions, and recommended validation steps.
+
+## Workflow Rules
+
+- Match fidelity to risk and decision maturity.
+- Do not polish a structure that has not been validated.
+- Prefer reusable system improvements over one-off fixes.
+- Treat accessibility and responsive behavior as design requirements.
+- Keep handoff notes specific enough that another teammate can build or review
+  the work.