forge-orkes 0.3.8 → 0.3.10

package/template/.claude/skills/designing/SKILL.md

@@ -1,92 +1,76 @@
 ---
 name: designing
-description: "Use when building UI: component selection, visual design, responsive layouts, accessibility, design system consistency. Trigger whenever the deliverable includes visible UI. Reads design system config from .forge/project.yml and component mappings from .forge/design-system.md."
+description: "Build consistent, accessible UIs using the project's design system. Reads config from .forge/project.yml and component mappings from .forge/design-system.md."
 ---
 
 # Designing
 
-Build consistent, accessible UIs by using the project's design system, not fighting it.
-
 ## Step 1: Load Design System Config
 
-Read the project's design system configuration:
-
 ```
 Read: .forge/project.yml → design_system section
 Read: .forge/design-system.md (component mapping table)
 ```
 
-If neither exists, this project hasn't been initialized with a design system. Ask the user:
-- *"This project doesn't have a design system configured. Would you like to set one up now, or proceed without design system enforcement?"*
+If neither exists, ask the user: set one up now, or proceed without design system enforcement?
 
-If `design_system.library` is `none`, skip component enforcement and focus on general design principles (accessibility, responsiveness, loading states).
+If `design_system.library` is `none`, skip component enforcement. Focus on accessibility, responsiveness, and loading states.
 
 ## Step 2: Component Mapping
 
-The component mapping table in `.forge/design-system.md` is the source of truth. It maps UI needs to specific components from the project's library.
+The mapping table in `.forge/design-system.md` is the source of truth — maps UI needs to library components.
 
-**When building any UI element**, check the mapping table first:
-1. Look up the UI need (data table, modal, dropdown, etc.)
-2. Use the mapped component with the documented props
-3. If the UI need isn't in the table → check the library's docs → add to the table
+For every UI element:
+1. Look up the UI need in the mapping table
+2. Use the mapped component with documented props
+3. If unmapped → check library docs → add to the table
 
-**Never build custom HTML/CSS for patterns the design system provides.** This is the single most important rule.
+**Never build custom HTML/CSS for patterns the design system provides.**
 
 ## Step 3: Style Rules
 
-These rules adapt based on the configured design system:
-
-1. **Use the design system's tokens, NOT custom CSS values**
+1. **Design system tokens, not custom CSS values**
    - Read `design_system.theme_approach` from project.yml
    - Bad: `style={{color: '#3B82F6', padding: '12px'}}`
-   - Good: Use the library's utility classes or theme tokens
+   - Good: Library utility classes or theme tokens
 
-2. **Use design system components, NOT raw HTML**
+2. **Design system components, not raw HTML**
    - Bad: `<table><thead><tr><th>` for data display
-   - Good: The library's table/data grid component
-   - Bad: `<div className="modal-overlay">` with absolute positioning
-   - Good: The library's dialog/modal component
+   - Good: Library's table/data grid component
 
-3. **Use the configured icon set**
-   - Read `design_system.icon_set` from project.yml
-   - Use only icons from this set for consistency
+3. **Configured icon set only** — read `design_system.icon_set` from project.yml
 
-4. **Use the configured layout system**
-   - Read `design_system.layout_system` from project.yml
-   - Use its grid/flex utilities for responsive layouts
-   - Never hardcode pixel widths for responsive layouts
+4. **Configured layout system** — read `design_system.layout_system` from project.yml. Never hardcode pixel widths for responsive layouts.
 
-5. **Theme customization goes in theme files, not inline**
-   - Override theme variables in the designated theme config
-   - Never scatter theme overrides across component files
+5. **Theme overrides in theme files, not inline** — never scatter overrides across component files
 
 ## Step 4: General Design Principles
 
-These apply regardless of which design system is used (or if none is used).
+Apply regardless of design system choice.
 
 ### Accessibility
 - Every interactive element needs a label (visible or `aria-label`)
-- Color is never the only indicator (use icons + color)
+- Color is never the only indicator — pair with icons
 - Keyboard navigation works for all interactive elements
-- Focus indicators are visible
-- Most design system components handle a11y by default — don't override it
+- Focus indicators visible
+- Design system components handle a11y by default — don't override
 
 ### Responsive Design
 - Mobile-first: design for small screens, enhance for large
 - Use the layout system's breakpoints
-- Test at 320px, 768px, 1024px, 1440px widths
-- Tables should scroll horizontally on mobile
+- Test at 320px, 768px, 1024px, 1440px
+- Tables scroll horizontally on mobile
 
 ### Loading States
-- Always show loading indicators for async operations
-- Use skeleton loaders or spinners during data fetch
+- Show loading indicators for all async operations
+- Skeleton loaders or spinners during data fetch
 - Disable submit buttons while processing
 
 ### Form Patterns
-- Labels above inputs, not beside (better for mobile and a11y)
-- Validation messages appear near the relevant field
-- Submit buttons show loading state during submission
-- Forms use the design system's form components
+- Labels above inputs (better for mobile and a11y)
+- Validation messages near the relevant field
+- Submit buttons show loading state
+- Use the design system's form components
 
 ## Step 5: Output Checklist
 
@@ -96,15 +80,13 @@ These apply regardless of which design system is used (or if none is used).
 - [ ] Configured icon set used for all icons
 - [ ] Responsive layout using configured layout system
 - [ ] Keyboard navigation works
-- [ ] Loading states present for all async operations
+- [ ] Loading states for all async operations
 - [ ] Forms use proper labels and validation messages
 
 ## Creating a New Design System Config
 
-When setting up a design system during project init (or later), follow this process:
-
-1. **Research the library**: Use `researching` skill to pull component docs
-2. **Build the mapping table**: Create `.forge/design-system.md` with this structure:
+1. Research the library via the `researching` skill
+2. Build `.forge/design-system.md`:
 
 ```markdown
 # Design System: {Library Name}
@@ -118,7 +100,6 @@ Docs: {docs_url}
 | Data table | `<ComponentName>` | `prop1`, `prop2` | `<ComponentName prop1={val} />` |
 | Modal | ... | ... | ... |
 | Dropdown | ... | ... | ... |
-| ... | ... | ... | ... |
 
 ## Style Rules
 
@@ -129,6 +110,6 @@ Docs: {docs_url}
 {How to use icons from the configured icon set}
 ```
 
-3. **Validate with user**: Present the mapping and ask if anything is missing or wrong.
+3. Present the mapping to the user for validation
 
-Example configs for common libraries are available in `.forge/templates/design-systems/` as starting points.
+Example configs in `.forge/templates/design-systems/`.