igorescodro 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
localizationskill 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:
- No design spec or spec is incomplete → STOP. Use
superpowers:brainstormingfirst. - 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 → UseKuvioBodyMediumText()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, tokensresources/— Strings, colors, spacing- Reference:
/assets/designsystem/alkaa-ds.html