igorescodro/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