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, tokensresources/ — Strings, colors, spacing- Reference:
/assets/designsystem/alkaa-ds.html
Source: igorescodro/alkaa — distributed by TomeVault.
1---2name: write-design-system-component3description: Use when implementing a new Kuvio component for the Alkaa Design System after design spec and structure decisions are finalized4---56# Kuvio Component Implementation78## Overview910Kuvio 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.1112**Prerequisite:** Design spec must be finalized (variants, layout, interactive states) before using this skill. If not, use `superpowers:brainstorming` first.1314## Steps15161. **Extract Design Spec** — Identify visual structure, variants, spacing, typography, interactive states → see `references/IMPLEMENTATION_GUIDE.md`172. **Study Existing Components** — Read at least 2 reference implementations → see `references/IMPLEMENTATION_GUIDE.md`183. **Choose Output Directory** — Map component category to folder → see `references/IMPLEMENTATION_GUIDE.md`194. **Implement Component** — Follow naming, code style, and slot conventions → see `references/IMPLEMENTATION_GUIDE.md`205. **Externalize Strings** — Use `localization` skill for all user-visible strings216. **Add Previews** — Light + dark pair for every meaningful variant → see `references/IMPLEMENTATION_GUIDE.md`227. **Verify Code Quality** — Run `scripts/verify_quality.sh`238. **Report** — List files created, variants exposed, slots, dependencies, design tokens used → see `references/IMPLEMENTATION_GUIDE.md`2425## Quick Reference2627| Rule | Correct | Wrong |28|------|---------|-------|29| **Naming** | `KuvioTaskChip` | `TaskChip`, `TASK_CHIP` |30| **Strings** | `stringResource(Res.string.kuvio_component_label)` | `"Add task"` |31| **Colors** | `MaterialTheme.colorScheme.primary` | `Color(0xFF123456)` |32| **Text** | `KuvioBodyMediumText()` | `Text(fontSize=14.sp, ...)` |33| **Size** | ~60 lines, max 3 nesting levels | 200+ lines, deeply nested |34| **Slots** | `icon: (@Composable () -> Unit)?` | `iconColor: Color, iconSize: Dp, ...` |35| **Constants** | `private const val AddTaskPlaceholder` | `private const val ADD_TASK_PLACEHOLDER` |3637## Red Flags — STOP and Review3839**Before Implementation:**40- [ ] No design spec or spec is incomplete → STOP. Use `superpowers:brainstorming` first.41- [ ] Unsure which variants, slots, or states the component needs → STOP. Finalize design first.4243**During Implementation:**44- [ ] About to hardcode a color → Use `MaterialTheme.colorScheme.*`45- [ ] Function approaching 80+ lines → Extract private sub-composables46- [ ] Nesting deeper than 3 levels → Extract logical chunks47- [ ] Raw `Text()` instead of Kuvio text primitive → Use `KuvioBodyMediumText()` etc.48- [ ] Strings in code (except Preview constants) → Move to `resources/strings.xml`4950**After Writing Code:**51- [ ] Skipping quality check → Run `scripts/verify_quality.sh`52- [ ] Preview doesn't match design spec → Fix before finishing5354## Common Mistakes5556| Mistake | Fix |57|---------|-----|58| Hardcoding colors | Breaks dark mode — use `MaterialTheme.colorScheme.*` |59| Raw `Text()` instead of Kuvio text | Inconsistent typography — use `KuvioBodyMediumText()` etc. |60| Strings in code | Not localizable — move to `resources/strings.xml` |61| Function > 60 lines | Hard to read — extract private sub-composables |62| Deep nesting (4+ levels) | Extract logical chunks to private composables |63| Configuration objects | Hard to extend — use composable `(@Composable () -> Unit)?` slots |64| Skipping previews | Can't verify visually — add light/dark pair for each variant |65| `Canvas` for shapes | Hard to theme — use `Box`, `clip`, `background` modifiers |6667## Design System Context6869- `libraries/designsystem/` — Kuvio components, theme, tokens70- `resources/` — Strings, colors, spacing71- Reference: `/assets/designsystem/alkaa-ds.html`7273---74> Source: [igorescodro/alkaa](https://github.com/igorescodro/alkaa) — distributed by [TomeVault](https://tomevault.io).75<!-- tomevault:4.0:skill_md:2026-06-19 -->
tomevault-io