| name | write-design-system-component |
| description | Use when implementing a new Kuvio component for the Alkaa Design System after design spec and structure decisions are finalized |
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
- Extract Design Spec — Identify visual structure, variants, spacing, typography, interactive states → see
references/IMPLEMENTATION_GUIDE.md
- Study Existing Components — Read at least 2 reference implementations → see
references/IMPLEMENTATION_GUIDE.md
- Choose Output Directory — Map component category to folder → see
references/IMPLEMENTATION_GUIDE.md
- Implement Component — Follow naming, code style, and slot conventions → see
references/IMPLEMENTATION_GUIDE.md
- Externalize Strings — Use
localization skill for all user-visible strings
- Add Previews — Light + dark pair for every meaningful variant → see
references/IMPLEMENTATION_GUIDE.md
- Verify Code Quality — Run
scripts/verify_quality.sh
- 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:
During Implementation:
After Writing Code:
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