Write Design System Component
Developmentwrite-design-system-componentWrite Design System Component is an Agent Skill for development published in the igorescodro/alkaa repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
Use when implementing a new Kuvio component for the Alkaa Design System after design spec and structure decisions are finalized
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/igorescodro/alkaa/blob/HEAD/.claude/skills/write-design-system-component/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/write-design-system-component, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
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