pi-design-deck 0.1.1 → 0.3.0

package/prompts/deck.md

@@ -1,7 +1,9 @@
 ---
 description: Present visual design options via design deck
 ---
-Load the `design-deck` skill for the full format reference. Analyze the current codebase and context, and present concrete visual options using `design_deck`.
+Load the `design-deck` skill for the full format reference. If presenting UI component options (tabs, trees, buttons, accordions, etc.), also read the relevant file from the skill's `references/component-gallery/` directory — it has visual vocabulary across design systems plus guidance on when to use distinct systems vs variations of the same approach.
+
+Analyze the current codebase and context, and present concrete visual options using `design_deck`.
 
 Read relevant files aggressively first so you understand the real constraints before generating options. If there's a plan or PRD, read it in full along with every codebase file it references — understand the actual state of the code, not just what the document assumes. Then identify the key design and architecture decisions and present options for each.
 

package/skills/design-deck/SKILL.md

@@ -3,6 +3,8 @@ name: design-deck
 description: Present visual options for architecture, UI, and code decisions with high-fidelity side-by-side previews. For comparing approaches visually — code diffs, diagrams, UI mockups, images — not for gathering structured input (use interview for that). Supports previewBlocks (code, mermaid, image, html), previewHtml, generate-more loops, and plan/PRD-driven flows.
 ---
 
+> **`design_deck` is a direct tool — call it directly, not via MCP.**
+
 # Design Deck Workflow
 
 Use this skill when the task requires presenting multiple visual directions and collecting explicit user choices. Load this skill before building any deck to get the full format reference.
@@ -201,6 +203,40 @@ surf gemini "isometric database cluster, dark theme, blue nodes" \
 **Combine images with other blocks:**
 An image showing the visual direction paired with a code block showing the implementation approach, or a mermaid diagram showing data flow alongside a generated image showing the UI that flow produces.
 
+### Component Gallery Reference
+
+When generating UI component options (tabs, accordions, tree views, buttons, etc.), read `./references/component-gallery/components.md` for best practices, common layouts, and aliases for 60 UI components.
+
+The reference enables three things:
+- **Discovery** — list, find, and suggest components for a use case ("I need expandable content" → accordion, disclosure, details)
+- **Cross-referencing** — connect related terms (collapse = accordion = disclosure = expander; notification = alert = banner)
+- **Design vocabulary** — know what design systems look like (Blueprint = dense, dark-native; Ant = clean, blue primary)
+
+The `INDEX.md` provides a design system vocabulary table (Ant Design, Blueprint, Carbon, Material, etc.) and guidance on when to use distinct systems vs variations.
+
+**Decide based on context:**
+- **Distinct systems** (Blueprint vs Ant vs 98.css) when exploring the design space with no established aesthetic
+- **Variations within a system** when the project already has a design direction or the user specifies a style
+
+See `./references/component-gallery/INDEX.md` for the decision table and examples.
+
+**Proactively browse real examples:** When you need visual inspiration for a component, fetch the component.gallery page directly:
+
+- https://component.gallery/components/tabs/ — 80+ real tab implementations
+- https://component.gallery/components/accordion/ — 100+ accordion examples
+- https://component.gallery/components/button/ — 120+ button styles
+
+Each page shows real screenshots from Ant Design, Blueprint, Carbon, Material, Shopify Polaris, and 90+ other design systems. Useful when you need concrete visual references — not required for every deck.
+
+**When user vocabulary is unclear or ambiguous:** Read `./references/component-gallery/LOOKUP.md` to resolve user terms to canonical component names. The lookup file provides:
+
+1. **Alias Index** — Direct mappings like `collapse → Accordion`, `snackbar → Toast`
+2. **Disambiguation** — Rules for ambiguous terms like `dropdown` (Select? Combobox? Dropdown menu?) or `popup` (Modal? Popover? Tooltip?)
+3. **Intent Clusters** — When users describe what they're trying to do ("I need users to pick from options"), maps constraints to components
+4. **Clarification Templates** — Suggested questions when disambiguation is needed
+
+Use the lookup before generating options if the user's component vocabulary seems imprecise or you're unsure which component they mean.
+
 ### For Mixed Previews
 
 Many slides benefit from combining block types — a mermaid diagram showing structure alongside a code block showing usage, or an HTML mockup with a code block showing the component API.
@@ -220,27 +256,27 @@ Use these selections as the implementation contract for the final build.
 
 ## Generate-More Loop
 
-When the user clicks generate-more, `design_deck` returns a result instructing which slide needs another option and listing existing option labels.
+When the user clicks generate-more, `design_deck` returns a result instructing which slide needs options and how many, along with the existing option labels.
 
-Generate one new option that is meaningfully distinct from the listed options.
+Generate the requested number of new options, each meaningfully distinct from the existing ones.
 
-Re-invoke:
+Re-invoke with all options in a single call:
 
-`design_deck({ action: "add-option", slideId: "...", option: "{...json string...}" })`
+`design_deck({ action: "add-options", slideId: "...", options: "[{...}, {...}]" })`
 
-The `add-option` call pushes the new option into the live deck and blocks again for the next user action.
+The `add-options` call pushes all options into the live deck and blocks for the next user action. Use `add-options` (plural) for generate-more requests — it takes an array and handles blocking automatically.
 
 ### Model Override
 
 The deck shows a model dropdown below the header (when 2+ models are available). Users can pick which model generates new options and optionally save it as the default.
 
-When the generate-more result includes a model instruction (e.g. "Generate using model X via deck_generate"), use the built-in `deck_generate` tool to generate the option with that model:
+When the generate-more result includes a model instruction (e.g. "Generate using model X via deck_generate"), use the built-in `deck_generate` tool to generate the options with that model:
 
 ```
-deck_generate({ model: "google/gemini-3.1-pro", task: "Generate a JSON deck option..." })
+deck_generate({ model: "google/gemini-3.1-pro", task: "Generate JSON deck options..." })
 ```
 
-Parse the output as the option JSON and pass it to `add-option`.
+Parse the output as the options JSON array and pass it to `add-options`.
 
 The default model can also be set in `~/.pi/agent/settings.json`:
 

package/skills/design-deck/references/component-gallery/INDEX.md

@@ -0,0 +1,88 @@
+# Component Gallery Reference
+
+Production-grade UI component knowledge — 2,676 real-world examples from 60 components across 100+ design systems, plus best practices and layout patterns.
+
+## File Structure
+
+| File | Purpose |
+|------|---------|
+| `components.md` | Best practices, common layouts, and aliases for all 60 components |
+| `LOOKUP.md` | Vocabulary resolution — maps user terms to canonical component names |
+| `components/INDEX.md` | Browsable index of all design system implementations |
+| `components/{category}.md` | Design system examples with URLs and preview images |
+
+## When to Read What
+
+| Situation | Read |
+|-----------|------|
+| Building deck options for a UI component | `components.md` for best practices |
+| User's term is ambiguous ("dropdown", "popup") | `LOOKUP.md` to resolve vocabulary |
+| Need concrete visual references from real design systems | `components/{category}.md` |
+| Want to see how Blueprint/Ant/Carbon implements X | `components/{category}.md` for URLs |
+
+## Categories
+
+- **[Actions](components/actions.md)** (294 examples) — Button, Button group, Dropdown menu, Link, Segmented control
+- **[Navigation](components/navigation.md)** (281 examples) — Breadcrumbs, Navigation, Pagination, Skip link, Stepper, Tabs
+- **[Inputs](components/inputs.md)** (726 examples) — Checkbox, Combobox, Datepicker, Select, Slider, Text input, Toggle, etc.
+- **[Data Display](components/data-display.md)** (663 examples) — Accordion, Avatar, Badge, Card, Table, Tree view, etc.
+- **[Feedback](components/feedback.md)** (420 examples) — Alert, Progress bar, Skeleton, Spinner, Toast, Tooltip
+- **[Overlays](components/overlays.md)** (170 examples) — Drawer, Modal, Popover
+- **[Layout](components/layout.md)** (111 examples) — Footer, Header, Hero, Separator, Stack
+- **[Utilities](components/utilities.md)** (11 examples) — Visually hidden
+
+## Design System Visual Languages
+
+Use this table as vocabulary for generating distinct options:
+
+| Design System | Visual Language | Good For |
+|---------------|-----------------|----------|
+| **98.css** | Windows 95 retro, beveled borders, system fonts | Nostalgic, developer tools |
+| **Ant Design** | Clean lines, blue primary, minimal chrome | Modern web apps, dashboards |
+| **Blueprint** | Dense, utilitarian, dark-mode native, monospace | Developer tools, data-dense UIs |
+| **Carbon** | IBM enterprise, subtle depth, structured grid | Enterprise apps, B2B |
+| **Material** | Elevation shadows, ripple effects, bold color | Consumer apps, mobile-first |
+| **Chakra** | Composable, accessible defaults, clean aesthetic | React apps, rapid prototyping |
+| **Radix** | Unstyled primitives, accessibility-first | Custom design systems |
+| **shadcn/ui** | Tailwind-based, copy-paste components | Next.js apps, modern stacks |
+| **Spectrum** | Adobe polish, refined interactions | Creative tools |
+| **Shoelace** | Web components, themeable | Framework-agnostic projects |
+
+## When to Use Distinct Systems vs Variations
+
+| Context | Approach |
+|---------|----------|
+| Exploring the design space | **Distinct systems** — Blueprint vs Ant vs 98.css |
+| Project has established aesthetic | **Variations within that system** |
+| User specifies a style | **Variations of that style** |
+| Early exploration, no constraints | **Distinct systems** — maximize range |
+
+## Using the Design System Examples
+
+Each entry in `components/{category}.md` includes:
+
+```
+- [ComponentName](url) — DesignSystem · Tech · Features · [preview](imageUrl)
+```
+
+**Example from inputs.md:**
+```
+- [Checkbox](https://ant.design/components/checkbox) — Ant Design · React — Code examples, Open source · [preview](https://component.gallery/_astro/...)
+```
+
+Use the URLs to:
+- Reference actual documentation when generating options
+- View preview images for visual inspiration
+- Note the tech stack (React, Vue, Web Components) for context
+
+## Workflow
+
+1. **Resolve vocabulary** — Check `LOOKUP.md` if the user's term is ambiguous
+2. **Read best practices** — `components.md` for the component's patterns and layouts
+3. **Browse implementations** — `components/{category}.md` for real examples
+4. **Generate distinct options** — Apply different design system vocabularies
+
+## Attribution
+
+- Component knowledge from [ui-design-brain](https://github.com/carmahhawwari/ui-design-brain) by [@Carmahhawwari](https://x.com/Carmahhawwari)
+- Design system examples from [component.gallery](https://component.gallery) by [Iain Bean](https://iainbean.com)