write-design-system-component

# Kuvio Component Implementation ## Overview Kuvio is the Alkaa Design System's component library. This skill guides implementation of theme-aware, multiplatform Compose Multiplatform components following strict naming, structure, and styling conventions. **Prerequisite:** Design spec must be finalized (variants, layout, interactive states) before using this skill. If not, use `superpowers:brainstorming` first. ## Steps 1. **Extract Design Spec** — Identify visual structure, variants, spacing, typography, interactive states → see `references/IMPLEMENTATION_GUIDE.md` 2. **Study Existing Components** — Read at least 2 reference implementations → see `references/IMPLEMENTATION_GUIDE.md` 3. **Choose Output Directory** — Map component category to folder → see `references/IMPLEMENTATION_GUIDE.md` 4. **Implement Component** — Follow naming, code style, and slot conventions → see `references/IMPLEMENTATION_GUIDE.md` 5. **Externalize Strings** — Use `localization` skill for all user-visible strings 6. **Add Previews** — Light + dark pair for every meaningful variant → see `references/IMPLEMENTATION_GUIDE.md` 7. **Verify Code Quality** — Run `scripts/verify_quality.sh` 8. **Report** — List files created, variants exposed, slots, dependencies, design tokens used → see `references/IMPLEMENTATION_GUIDE.md` ## Quick Reference | Rule | Correct | Wrong | |------|---------|-------| | **Naming** | `KuvioTaskChip` | `TaskChip`, `TASK_CHIP` | | **Strings** | `stringResource(Res.string.kuvio_component_label)` | `"Add task"` | | **Colors** | `MaterialTheme.colorScheme.primary` | `Color(0xFF123456)` | | **Text** | `KuvioBodyMediumText()` | `Text(fontSize=14.sp, ...)` | | **Size** | ~60 lines, max 3 nesting levels | 200+ lines, deeply nested | | **Slots** | `icon: (@Composable () -> Unit)?` | `iconColor: Color, iconSize: Dp, ...` | | **Constants** | `private const val AddTaskPlaceholder` | `private const val ADD_TASK_PLACEHOLDER` | ## Red Flags — STOP and Review **Before Implementation:** - [ ] No design spec or spec is incomplete → STOP. Use `superpowers:brainstorming` first. - [ ] Unsure which variants, slots, or states the component needs → STOP. Finalize design first. **During Implementation:** - [ ] About to hardcode a color → Use `MaterialTheme.colorScheme.*` - [ ] Function approaching 80+ lines → Extract private sub-composables - [ ] Nesting deeper than 3 levels → Extract logical chunks - [ ] Raw `Text()` instead of Kuvio text primitive → Use `KuvioBodyMediumText()` etc. - [ ] Strings in code (except Preview constants) → Move to `resources/strings.xml` **After Writing Code:** - [ ] Skipping quality check → Run `scripts/verify_quality.sh` - [ ] Preview doesn't match design spec → Fix before finishing ## Common Mistakes | Mistake | Fix | |---------|-----| | Hardcoding colors | Breaks dark mode — use `MaterialTheme.colorScheme.*` | | Raw `Text()` instead of Kuvio text | Inconsistent typography — use `KuvioBodyMediumText()` etc. | | Strings in code | Not localizable — move to `resources/strings.xml` | | Function > 60 lines | Hard to read — extract private sub-composables | | Deep nesting (4+ levels) | Extract logical chunks to private composables | | Configuration objects | Hard to extend — use composable `(@Composable () -> Unit)?` slots | | Skipping previews | Can't verify visually — add light/dark pair for each variant | | `Canvas` for shapes | Hard to theme — use `Box`, `clip`, `background` modifiers | ## Design System Context - `libraries/designsystem/` — Kuvio components, theme, tokens - `resources/` — Strings, colors, spacing - Reference: `/assets/designsystem/alkaa-ds.html`