This skill addresses the question of "how to correctly integrate the OpenDesign design system into an engineering project" — aimed atdevelopers creating a new project or retrofitting an existing project to adopt OpenDesign , covering scaffolding, theme system integration, global style infrastructure, directory organization, coding conventions, and code review inspection.
Provides two sets ofdirectly cloneable and runnablescaffolds (templates/）：
| Scaffold | Path | Form | Applicable scenarios |
|---|---|---|---|
| Nuxt 4 SSR | templates/nuxt |
Server-side rendering + static generation | Official websites, content sites, scenarios requiring SEO |
| Vite + Vue 3 SPA | templates/vue-spa |
Single-page application | Backend management, tool sites, applications that do not require SSR |
Both scaffolds have completed: OpenDesign theme initialization, Pinia theme store, SCSS mixin global injection, responsive grid container,AppSection section component(uniformly consuming design tokens to handle section-level width/spacing/title typography specifications), fully token-driven styling. Each scaffold root directory contains AGENTS.md— providing architectural constraints, component splitting specifications, common abstraction patterns, and best practice guidance for AI coding tools (and designers unfamiliar with code), ensuring that compliant code can be produced according to specifications even without a front-end engineering background.
AGENTS.md in the scaffold
The AGENTS.md in each scaffold's root directory is operational guidance aimed atAI tools and designers working in the scaffold project(first layer), complementary to this SKILL.md(second layer: engineering integration reference):
| File | Aimed at | Core content |
|---|---|---|
templates/vue-spa/AGENTS.md |
AI tools / designers in Vite SPA projects | Architectural red lines, directory conventions, component splitting timing and principles, common abstraction templates (composable / store / mixin), section-based assembly patterns, style hard rule quick reference, common anti-patterns, infrastructure file list |
templates/nuxt/AGENTS.md |
AI tools / designers in Nuxt SSR projects | Same as above + SSR safety guards(hydration mismatch prevention,<ClientOnly> usage specifications,import.meta.client guards), Nuxt auto-import rules, Plugin classification specifications, data fetching composables |
Boundaries with peer skills
This skill only coversengineering integration, and does not repeat specific design system content:
| What you want to look up | Which skill to go to |
|---|---|
| Component Props / Events / Slots / Expose | ../opendesign-components/SKILL.md |
| Token variable names such as color / spacing / font size / border radius | ../opendesign-tokens/SKILL.md |
| Pixso design draft production specifications | ../opendesign-design/SKILL.md |
| Designer-side direct output of Vue SFC from design intent | ../opendesign-codegen/SKILL.md |
gen:icon / build:style CLI commands such as |
../opendesign-scripts/SKILL.md |
| Engineering integration, theme system, style infrastructure, code review | This skill |
Trigger scenarios
- New projects should adopt OpenDesign, but I don't know how to get started
- Existing projects need to integrate the OpenDesign theme system (Pinia + community switching)
- How to globally inject SCSS mixins and how to use grid containers
- What are the differences between Nuxt SSR and Vite SPA in OpenDesign integration
- During code review, check whether OpenDesign is used correctly(no :deep, tokens first, components first, style import order)
Engineering Overview
Red Lines (violation is considered integration failure)
- The style import order cannot be changed: Token CSS → HarmonyOS fonts → component library styles → project global styles. Tokens must come before component styles; otherwise components cannot get the CSS variables.
- Forbidden
:deep()Modify OpenDesign component internal styles. Global rules such as component internal width go inglobal.scssrendering classes (such as.o-form .o-input), scoped styles only manage the component's own layout. - Colors / spacing / font sizes are always
var(--o-*), hardcoded hex / px is forbidden. Semantic colors use--o-color-*, directly using palette variables (--o-kleinblue-*/--o-grey-*, etc.) is strictly forbidden. - Prefer OpenDesign components, for any capability already provided by the component library you must implement it with component props / slots / events, and do not create your own native replacements.
- The theme is driven by
<html data-o-theme="社区.模式">Driven, business code does not directly manipulate CSS variables to switch themes; go through the Pinia store'sisDark(writable computed) orsetMode。
Getting Started
- Choose a community theme (
e/a/k/m/g/u) — see../opendesign-tokens/SKILL.md's six-community description - Clone the corresponding scaffold (Nuxt or Vite SPA) as the starting point
- Change the
OPENDESIGN_COMMUNITYconstants and token CSS imports to your selected community - Read the references below as needed to complete customization
Reference File Index
| Theme | File | Content |
|---|---|---|
| Scaffold Guide | templates/vue-spa/AGENTS.md | Vite SPA architecture constraints, component splitting, common abstractions, best practices, anti-patterns (for AI tools / designers) |
| Scaffold Guide | templates/nuxt/AGENTS.md | Nuxt SSR same as above + SSR safety guards,<ClientOnly>, auto-imports, Plugin, data fetching |
| Getting Started | references/getting-started.md | Dependency installation, entry files, style import order,initRound、useScreen(), minimal runnable example |
| Theme System | references/theme-system.md | Pinia store, SSR hydration, VueUse, community switching, ThemeToggle (OSwitch) |
| Style Infrastructure | references/styles-infrastructure.md | Three sets of SCSS mixins (including hover), global injection,useScreen() runtime detection, global.scss, grid containers, AppSection floor components |
| Project Layout | references/project-layout.md | Directory structure, Nuxt vs Vite SPA difference comparison, selection recommendations |
| Coding Conventions | references/conventions.md | Hard rules, application-layer conventions,Code Review checklist, violation corrections |
Code Review Quick Reference (OpenDesign-related review items)
For the complete checklist, see references/conventions.md 's "Code Review Checklist" chapter.
| Review Item | Compliance | Violation signal |
|---|---|---|
| Style import order | Token → Font → Component styles → Global styles | Component styles before Token |
:deep Use |
No :deep(.o-*)in scoped styles; customize component styles via CSS variables / slots / props |
Presence of :deep(.o-input) etc. |
| Color values | var(--o-color-*) semantic token |
Hardcoded #fff / var(--o-grey-14) color palette |
| Spacing / font size / line height | var(--o-gap-*) / font size + line height as a pair (@include h* or var(--o-r-font_size-*) + var(--o-r-line_height-*)); using only one intentionally requires a comment |
Hardcoded 16px / specifying only font size without line height and no comment |
| Font weight / animation | var(--o-font_weight-*) / var(--o-duration-*) + var(--o-easing-*) |
Hardcoded 600 / 300ms / cubic-bezier(...) |
| Component first | <OButton> / <OInput> and other real components |
Native <button> / <select> replacement |
| Form control width | global.scss Render references the width variable exported by OForm (refer to the scaffold template) |
Inside component scoped :deep Modify control width; hardcode width: 200px |
| Theme switching | Use the store's isDark(writable computed) or setMode |
Directly document.setAttribute operation |
| Inline styles | No style="..."(except dynamic values) |
Large amount of inline style |
| hover interaction | @include hover(safe hover) / @include hoverable |
Bare :hover or bare @media (hover: hover) |
| Responsive detection | useScreen() composable + <ClientOnly>（Nuxt） |
Bare window.matchMedia or missing <ClientOnly> causing hydration mismatch |
| mixin vs useScreen | CSS style changes go through mixin; only use useScreen + v-if when the DOM structure differs | Pure style changes but using useScreen + :style/:class |
| Icon usage | gen:icon generated components (#icons alias import) |
Inline <svg> tag replacement |