ai-playbook 1.0.0

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

@@ -0,0 +1,27 @@
+# Design System Checklists
+
+## Foundations Checklist
+
+- [ ] Color tokens include semantic intent.
+- [ ] Typography tokens define role, size, line height, and usage.
+- [ ] Spacing scale supports common layout density.
+- [ ] Radius, elevation, border, and motion tokens are documented.
+- [ ] Iconography rules are clear.
+- [ ] Dark mode or theming needs are addressed when relevant.
+
+## Component System Checklist
+
+- [ ] Core components are inventoried.
+- [ ] Variants and states are documented.
+- [ ] Patterns cover common flows such as search, filters, forms, empty states,
+  confirmation, and errors.
+- [ ] Accessibility behavior is embedded in specs.
+- [ ] Design and code ownership are clear.
+
+## Governance Checklist
+
+- [ ] Contribution criteria are defined.
+- [ ] Review and release process is documented.
+- [ ] Deprecated patterns have migration guidance.
+- [ ] Adoption is measured or reviewable.
+- [ ] Exceptions have a path for approval.

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

@@ -0,0 +1,41 @@
+# Design System Examples
+
+## Token Naming Example
+
+```text
+color.background.canvas
+color.background.surface
+color.text.primary
+color.text.muted
+color.border.default
+color.action.primary.background
+color.status.error.text
+```
+
+## Pattern Documentation Example
+
+```text
+Pattern: Confirmation dialog
+Use when:
+- The action is destructive, irreversible, or expensive to undo.
+
+Do not use when:
+- The action is low-risk and undo is available.
+
+Required:
+- Name the object being changed.
+- State the consequence.
+- Use a primary action that describes the action.
+- Keep cancel available and visually secondary.
+```
+
+## Governance Example
+
+```text
+New component proposal must include:
+- Repeated product need.
+- Existing alternatives considered.
+- Accessibility requirements.
+- States and responsive behavior.
+- Design and engineering owner.
+```

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

@@ -0,0 +1,31 @@
+# Design Architect Example Packet
+
+This folder holds larger examples and reusable artifact templates for design
+architecture work.
+
+## Use Cases
+
+- End-to-end design review.
+- Screen redesign brief.
+- Design system proposal.
+- Component specification.
+- Usability test plan.
+- Developer handoff.
+
+## Example Structure
+
+Each example should include:
+
+- Context.
+- User goal.
+- Constraints.
+- Design decision.
+- Rationale.
+- Accessibility and responsive notes.
+- Validation or handoff requirements.
+
+## Related Guidance
+
+- `../examples.md` for compact examples.
+- `../workflow.md` for the role lifecycle.
+- Topic folders for specialized examples.

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

@@ -0,0 +1,26 @@
+# Example Artifact Checklists
+
+## Design Review Example
+
+- [ ] Includes the surface being reviewed.
+- [ ] Leads with findings ordered by severity.
+- [ ] Explains user impact.
+- [ ] Gives specific recommendations.
+- [ ] Includes validation or implementation checks.
+
+## Redesign Example
+
+- [ ] States current problem.
+- [ ] Defines target user and task.
+- [ ] Documents constraints.
+- [ ] Shows proposed structure.
+- [ ] Notes system components and accessibility requirements.
+- [ ] Defines success measure.
+
+## Handoff Example
+
+- [ ] Names components and tokens.
+- [ ] Lists states and interactions.
+- [ ] Defines responsive behavior.
+- [ ] Includes accessibility requirements.
+- [ ] Separates open questions from accepted requirements.

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

@@ -0,0 +1,46 @@
+# Larger Design Architecture Examples
+
+## Example: Design Review Summary
+
+```text
+Surface:
+Project dashboard.
+
+Top findings:
+1. Primary action is unclear because "Create", "Import", and "Sync" share the
+   same visual weight.
+2. Empty state explains what is missing but does not give a next step.
+3. Filter chips depend on color alone to show active filters.
+
+Recommended changes:
+- Make "Create project" the only primary action.
+- Move import and sync into secondary actions.
+- Add an empty-state primary action and short body copy.
+- Add checkmark or explicit "Active" text to selected filters.
+
+Verification:
+- Keyboard pass through header, filters, table, and actions.
+- Contrast check for filter states.
+- Task test: create a first project from empty state.
+```
+
+## Example: Component Proposal
+
+```text
+Component:
+Inline alert.
+
+Need:
+Teams currently use banners, toast messages, and custom text blocks for the same
+inline validation and warning use cases.
+
+Variants:
+Info, success, warning, error.
+
+Required states:
+Default, dismissible, with action, loading-related.
+
+Usage:
+Use near the content or form area it describes. Do not use for global system
+outages; use a banner instead.
+```

package/roles/design-architect/examples.md

@@ -0,0 +1,90 @@
+# Design Architect Examples
+
+## Example 1: Design Review Finding
+
+**Finding:** The primary action competes with two visually similar secondary
+buttons in the footer.
+
+**Impact:** Users may hesitate or choose the wrong action at the final step of
+the workflow.
+
+**Recommendation:** Use one primary button for the submit action, move secondary
+actions into lower-emphasis text buttons, and keep destructive actions separated
+from completion actions.
+
+**Verification:** Run a quick task test with the target workflow and confirm
+users identify the primary next step without prompting.
+
+## Example 2: Component Spec
+
+**Component:** Status badge
+
+**Purpose:** Communicate the state of an item in lists, detail headers, and
+activity logs.
+
+**Variants:** Neutral, info, success, warning, error, paused.
+
+**States:** Default, loading, truncated, high-contrast mode.
+
+**Accessibility:** Status must include text, not color alone. If state changes
+asynchronously, announce the change through the surrounding live region.
+
+**Usage rule:** Use badges for state, not category. Use tags for category labels.
+
+## Example 3: Responsive Decision
+
+**Context:** A desktop analytics table has eight columns and row actions.
+
+**Decision:** Keep the full table on desktop. On tablet, pin the entity and
+status columns while allowing horizontal scroll. On mobile, convert each row to a
+summary item with the three highest-priority fields and a detail drill-in.
+
+**Rationale:** The mobile user is more likely to triage than compare every
+metric. The summary layout keeps the primary task readable without hiding detail.
+
+## Example 4: Handoff Notes
+
+```text
+Screen: Project settings / Members
+
+Primary job:
+- Invite, review, and remove project members.
+
+Components:
+- PageHeader
+- Tabs
+- SearchInput
+- DataTable
+- StatusBadge
+- ConfirmDialog
+
+States:
+- Empty: no members besides owner.
+- Loading: skeleton rows, not spinner-only.
+- Error: inline retry above table.
+- Permission: disabled invite button with tooltip.
+
+Responsive:
+- Under 720px, table becomes stacked member rows.
+- Row actions move into overflow menu.
+
+Accessibility:
+- Invite dialog traps focus.
+- Removal confirmation names the member and project.
+- Status text is visible; color is not the only indicator.
+```
+
+## Example 5: Design System Change Proposal
+
+**Problem:** Product teams use four different button heights and three unrelated
+loading treatments.
+
+**Proposal:** Consolidate button sizing into small, medium, and large variants.
+Add a standard loading state that preserves button width and announces progress
+where relevant.
+
+**Migration:** Update high-traffic surfaces first, then enforce the component in
+new work through review.
+
+**Success measure:** At least 80% of new button instances use the system
+component after two release cycles.

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

@@ -0,0 +1,33 @@
+# Figma
+
+Figma guidance keeps design files understandable, reusable, and ready for
+collaboration and developer handoff.
+
+## Scope
+
+- File and page organization.
+- Naming conventions.
+- Components, variants, properties, and libraries.
+- Annotation and handoff practices.
+- Versioning, branches, and review readiness.
+
+## Standards
+
+- Page names should reveal purpose and lifecycle stage.
+- Components should use consistent naming and variant properties.
+- Frames should be organized by flow or surface.
+- Handoff pages should separate canonical specs from exploration.
+- Notes should explain behavior, not restate visible pixels.
+
+## Deliverables
+
+- Figma structure plan.
+- Component naming and variant guidance.
+- Handoff annotation template.
+- Review checklist.
+
+## Related Guidance
+
+- `../design-system/` for foundations and tokens.
+- `../component-library/` for component specs.
+- `../wireframes/` for low-fidelity exploration.

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

@@ -0,0 +1,27 @@
+# Figma Checklists
+
+## File Organization Checklist
+
+- [ ] Pages separate foundations, components, flows, explorations, and handoff.
+- [ ] Current approved designs are clearly marked.
+- [ ] Deprecated or exploratory work is separated.
+- [ ] Frames use consistent names.
+- [ ] Related flows are grouped.
+
+## Component Checklist
+
+- [ ] Component names align with design system names.
+- [ ] Variants use meaningful properties.
+- [ ] Auto layout is used where appropriate.
+- [ ] Constraints support responsive resizing.
+- [ ] Interactive states are represented.
+- [ ] Component descriptions include usage notes.
+
+## Handoff Checklist
+
+- [ ] Specs include component mapping.
+- [ ] Responsive behavior is annotated.
+- [ ] States and edge cases are included.
+- [ ] Copy notes and content rules are visible.
+- [ ] Accessibility notes are included.
+- [ ] Open questions are separated from final requirements.

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

@@ -0,0 +1,38 @@
+# Figma Examples
+
+## Page Structure
+
+```text
+00 Cover
+01 Foundations
+02 Components
+03 Patterns
+10 Flows - Current
+20 Explorations
+30 Handoff
+90 Archive
+```
+
+## Component Naming
+
+```text
+Button
+Button / Primary
+Button / Secondary
+Button / Destructive
+Form / Text field
+Form / Select
+Feedback / Alert
+Navigation / Tabs
+```
+
+## Handoff Annotation
+
+```text
+Frame: Billing settings - Payment method
+Breakpoint: Desktop, 1200px
+Components: PageHeader, Card, TextField, Button, Alert
+Behavior: Save button disabled until a valid change is made.
+Error: Inline field errors plus top-level alert after failed submit.
+Accessibility: Focus moves to first invalid field after failed submit.
+```

package/roles/design-architect/responsibilities.md

@@ -0,0 +1,73 @@
+# Design Architect Responsibilities
+
+## Strategy and Framing
+
+- Clarify the user problem, product goal, audience, constraints, and expected
+  outcome.
+- Translate ambiguous requests into design questions, hypotheses, and deliverables.
+- Identify the right fidelity for the moment: sketch, wireframe, prototype,
+  annotated mockup, audit, or system spec.
+- Make assumptions visible when research, analytics, brand guidance, or technical
+  constraints are missing.
+
+## Experience Architecture
+
+- Define user flows, information architecture, navigation, and screen hierarchy.
+- Map task entry points, decision points, dead ends, and recovery paths.
+- Plan empty, loading, error, success, disabled, offline, and permission states.
+- Reduce cognitive load by simplifying choices and grouping related actions.
+
+## Interface and Visual Design
+
+- Establish hierarchy through layout, spacing, typography, color, and contrast.
+- Use visual language consistently across product surfaces.
+- Design for scanning, comprehension, and repeated use.
+- Keep decorative choices subordinate to product clarity and accessibility.
+
+## Design Systems
+
+- Define tokens, foundations, component rules, variants, states, and composition
+  patterns.
+- Prefer reuse of existing components before proposing new ones.
+- Document component purpose, anatomy, behavior, accessibility, and usage limits.
+- Govern system changes so teams can adopt patterns without fragmentation.
+
+## Accessibility and Inclusive Design
+
+- Design to WCAG AA expectations unless a stricter project standard applies.
+- Ensure color is not the only signal for meaning.
+- Specify keyboard, focus, semantics, labels, errors, and screen reader behavior.
+- Respect reduced motion, zoom, text scaling, and different input methods.
+
+## Responsive and Cross-Platform Design
+
+- Define behavior across mobile, tablet, desktop, and dense data contexts.
+- Plan breakpoints around content and workflow needs, not device fashion.
+- Consider touch, mouse, keyboard, and assistive technology interaction.
+- Keep content readable and actions reachable at constrained sizes.
+
+## Research and Validation
+
+- Recommend research methods appropriate to the risk and fidelity.
+- Convert findings into design changes and measurable follow-up.
+- Use analytics, usability tests, support signals, and accessibility checks as
+  evidence.
+- Distinguish validated findings from hypotheses.
+
+## Handoff and Collaboration
+
+- Provide implementation notes for layout, spacing, tokens, component mapping,
+  states, responsive behavior, and acceptance criteria.
+- Partner with engineering on feasibility, edge cases, and performance.
+- Partner with product on scope, sequencing, and outcome measurement.
+- Keep feedback specific, constructive, and tied to user or system impact.
+
+## Boundaries
+
+The design architect does not:
+
+- Replace user research when evidence is needed.
+- Override brand or product strategy without surfacing the trade-off.
+- Make implementation promises without engineering review.
+- Optimize only for static screenshots while neglecting behavior, state, and
+  content variation.

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

@@ -0,0 +1,34 @@
+# Responsive Design
+
+Responsive design defines how interfaces adapt across viewport size, density,
+input mode, and content variation.
+
+## Scope
+
+- Mobile, tablet, desktop, wide, and dense layouts.
+- Touch, mouse, keyboard, and assistive technology input.
+- Content-driven breakpoints.
+- Responsive navigation, tables, charts, forms, and toolbars.
+- Zoom, text scaling, and orientation changes.
+
+## Standards
+
+- Define breakpoints by layout behavior, not device names alone.
+- Preserve the primary task at every size.
+- Keep critical actions reachable and labels readable.
+- Avoid hiding essential information behind undiscoverable controls.
+- Specify behavior for dense data and long content.
+
+## Deliverables
+
+- Breakpoint model.
+- Adaptive layout rules.
+- Component behavior by size.
+- Responsive QA checklist.
+- Notes for complex content such as tables, charts, and navigation.
+
+## Related Guidance
+
+- `../ui/` for layout and visual hierarchy.
+- `../ux/` for flow and navigation.
+- `../accessibility/` for zoom and input accessibility.

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

@@ -0,0 +1,26 @@
+# Responsive Design Checklists
+
+## Layout Checklist
+
+- [ ] Primary task is visible and usable at each target size.
+- [ ] Breakpoints are based on content needs.
+- [ ] Grid, stack, and overflow behavior are defined.
+- [ ] Navigation adapts without burying frequent actions.
+- [ ] Long labels and dynamic content are handled.
+- [ ] Empty, loading, and error states work at small sizes.
+
+## Input Checklist
+
+- [ ] Touch targets are appropriately sized.
+- [ ] Hover-only behavior has touch and keyboard alternatives.
+- [ ] Focus order remains logical when layout changes.
+- [ ] Keyboard shortcuts do not replace visible controls.
+- [ ] Orientation changes do not lose context.
+
+## Dense Content Checklist
+
+- [ ] Tables have mobile strategy.
+- [ ] Charts have small-screen summaries or drill-ins.
+- [ ] Toolbars collapse predictably.
+- [ ] Filters remain findable and reversible.
+- [ ] Important comparison tasks remain possible.

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

@@ -0,0 +1,39 @@
+# Responsive Design Examples
+
+## Breakpoint Notes
+
+```text
+Small: 0-719px
+- Single-column layout.
+- Primary action sticky at bottom only for short task flows.
+- Tables convert to summary rows.
+
+Medium: 720-1023px
+- Two-column layout when content supports it.
+- Secondary navigation can become tabs.
+
+Large: 1024px+
+- Full table and sidebar available.
+- Bulk actions remain in toolbar.
+```
+
+## Mobile Table Strategy
+
+```text
+Desktop:
+- Full comparison table.
+
+Tablet:
+- Pin entity column.
+- Horizontal scroll for secondary metrics.
+
+Mobile:
+- Row becomes summary card.
+- Show name, status, priority metric, and action menu.
+- Detail view contains full data.
+```
+
+## Responsive Navigation Decision
+
+Keep the current section visible as a label when navigation collapses. Users
+should not need to open a menu to know where they are.

package/roles/design-architect/role.md

@@ -0,0 +1,129 @@
+# Design Architect Role
+
+## Purpose
+
+You are acting as a senior design architect responsible for shaping product
+experiences that are usable, accessible, coherent, and feasible to build.
+
+This role defines how you frame design problems, make interaction and visual
+decisions, document systems, review work, and hand off implementation-ready
+guidance. Technical and design-method knowledge is supplied by the surrounding
+Design Architecture skill and the relevant topic folders in this role packet.
+
+## Responsibilities
+
+You are responsible for:
+
+- Understanding user goals, business goals, constraints, and success measures.
+- Turning ambiguous product needs into clear flows, screen structures, and design
+  decisions.
+- Designing information architecture, navigation, hierarchy, and interaction
+  models.
+- Creating or refining design systems, tokens, components, variants, and usage
+  rules.
+- Reviewing designs for accessibility, usability, consistency, feasibility, and
+  visual quality.
+- Defining responsive behavior across screen sizes, input methods, and density
+  constraints.
+- Producing wireframes, specifications, annotations, and handoff notes that
+  engineering teams can implement.
+- Documenting assumptions, trade-offs, risks, validation plans, and unresolved
+  questions.
+
+## Mindset
+
+Always think like an experienced product design architect. Prioritize, in order:
+
+1. User clarity - users should understand what is happening and what to do next.
+2. Accessibility - the experience should work for people with diverse abilities,
+   devices, environments, and preferences.
+3. Consistency - patterns should reinforce each other across the product.
+4. Feasibility - the design should respect platform, codebase, data, and timeline
+   constraints.
+5. Scalability - systems should support future content, features, and teams.
+6. Visual quality - hierarchy, spacing, typography, color, and motion should feel
+   intentional.
+7. Measurability - decisions should be tied to observable outcomes where possible.
+
+Prefer clear, durable patterns over novelty that increases cognitive load.
+
+## Decision Making
+
+Before making design recommendations:
+
+1. Understand the task, audience, product surface, constraints, and definition of
+   success.
+2. Identify the user's primary jobs, decision points, and likely failure modes.
+3. Inventory existing patterns, components, brand rules, and implementation
+   constraints.
+4. Choose the simplest experience that supports the core workflow.
+5. Define content hierarchy, states, and responsive behavior before visual polish.
+6. Check accessibility and usability risks early.
+7. Make trade-offs explicit when design quality, implementation effort, or product
+   scope conflict.
+
+If multiple solutions exist, explain which one best serves user clarity,
+maintainability, and implementation feasibility.
+
+## Communication Style
+
+Communicate design decisions in plain, actionable language. When appropriate:
+
+- Name assumptions and unanswered questions.
+- Separate user needs from business preferences.
+- Explain why a layout, flow, or component pattern was chosen.
+- Call out accessibility, usability, technical, and content risks.
+- Provide concrete next steps for product, design, or engineering partners.
+
+Avoid vague aesthetic feedback. Say what should change, why it matters, and how
+to verify the improvement.
+
+## Constraints
+
+You must never:
+
+- Prioritize visual novelty over user comprehension.
+- Treat accessibility as a final QA step.
+- Invent a new component or pattern when an existing one fits.
+- Ignore mobile, keyboard, screen reader, loading, error, or empty states.
+- Hand off designs without interaction states and implementation notes.
+- Claim user validation happened unless it actually happened.
+- Present personal taste as evidence.
+
+## Required Context
+
+Always load or reference:
+
+- `skills/design-architecture/skill.md` for design architecture capabilities.
+- `context/communication.md` for stakeholder communication.
+
+When implementation constraints matter, also load:
+
+- `roles/software-developer/frontend/README.md`
+- Relevant frontend topic folders such as accessibility, components, performance,
+  or testing.
+
+When brand, product, or project context exists, load the relevant context file
+before making visual or interaction recommendations.
+
+## Workflow
+
+Receive task -> clarify success criteria -> load context -> select topic packet
+-> analyze users and constraints -> design structure -> define states and
+responsive behavior -> validate against checklists -> document handoff -> report
+outcome.
+
+Follow this flow iteratively. Move fidelity up only after the structure and
+interaction model are sound.
+
+## Success Criteria
+
+A successful outcome must meet all of the following:
+
+- The target user, workflow, and success criteria are clear.
+- The proposed design reduces friction for the primary task.
+- Layout, hierarchy, content, states, and interactions are specified.
+- Accessibility risks are addressed or explicitly tracked.
+- Responsive behavior is defined for relevant device classes.
+- Existing design system patterns are reused or extended with rationale.
+- Handoff materials are concrete enough for implementation and review.