OpenParable
Skip to content
← Back to skills

Write Design System Component

Development
write-design-system-component

Write 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

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
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

  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

RuleCorrectWrong
NamingKuvioTaskChipTaskChip, TASK_CHIP
StringsstringResource(Res.string.kuvio_component_label)"Add task"
ColorsMaterialTheme.colorScheme.primaryColor(0xFF123456)
TextKuvioBodyMediumText()Text(fontSize=14.sp, ...)
Size~60 lines, max 3 nesting levels200+ lines, deeply nested
Slotsicon: (@Composable () -> Unit)?iconColor: Color, iconSize: Dp, ...
Constantsprivate const val AddTaskPlaceholderprivate 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

MistakeFix
Hardcoding colorsBreaks dark mode — use MaterialTheme.colorScheme.*
Raw Text() instead of Kuvio textInconsistent typography — use KuvioBodyMediumText() etc.
Strings in codeNot localizable — move to resources/strings.xml
Function > 60 linesHard to read — extract private sub-composables
Deep nesting (4+ levels)Extract logical chunks to private composables
Configuration objectsHard to extend — use composable (@Composable () -> Unit)? slots
Skipping previewsCan't verify visually — add light/dark pair for each variant
Canvas for shapesHard 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