maooo-skyline-ui-system 0.1.4 → 0.1.6

package/miniprogram_dist/ai-design-system/DESIGN.md

@@ -0,0 +1,73 @@
+# Maooo Design System
+
+This is the single design-language entry for the `maooo-design` Skyline UI system. Read this file first before using prompts, skills, token source files, patterns, schemas, or component contracts.
+
+## Design Personality
+
+Maooo uses a warm, pet-service-oriented visual language: soft pink brand emphasis, high-contrast black text, light neutral surfaces, rounded cards, and clear service-state colors. The interface should feel friendly and reliable without becoming decorative or marketing-heavy.
+
+## Visual Principles
+
+- Use existing token source before creating any new visual value.
+- Keep page backgrounds light and quiet; use pink primarily for brand actions and light emphasis.
+- Use explicit text colors for selected, disabled, active, and similar states.
+- Do not use `color: inherit;` in component or demo WXSS.
+- Treat component dimensions in design boards as evidence until they are confirmed as reusable component contracts.
+- Keep Skyline compatibility in mind: prefer scoped styles, stable structure, and `scroll-view` for page scrolling.
+
+## Core Foundations
+
+| Area | Source | Notes |
+| --- | --- | --- |
+| Color | `design-system/tokens/source/color.json` | Semantic text, background, brand, amount, gender, border, and status values. |
+| Typography | `design-system/tokens/source/typography.json` | System font by default; visually aligns with `PingFang SC`; numeric evidence references `MiSans`. |
+| Spacing | `design-system/tokens/source/spacing.json` | Machine-readable spacing scale. Figma page margin evidence is not automatically a new token. |
+| Radius | `design-system/tokens/source/radius.json` | Includes none, sm, md, lg, xl, and pill. Circular avatars/buttons keep using `50%`. |
+| Shadow | `design-system/tokens/source/shadow.json` | Reusable shadow source. Figma guide-line shadow is board evidence only. |
+
+## Evidence Index
+
+| Source | Location | Purpose |
+| --- | --- | --- |
+| Figma user-side UI guideline | `design-system/references/figma-user-client-visual-evidence.md` | Raw visual evidence tables for color, typography, spacing, radius, shadow, layout, and component style. |
+| MasterGo color board | fileId `195541105840652`, layerId `41:3015` | Current token color and typography mapping evidence. |
+| MasterGo radius board | fileId `195541105840652`, layerId `9:2754` | Current radius scale evidence. |
+
+Figma component-size evidence, such as button heights, TabBar size, icon sizes, and tag dimensions, should guide component review but must not be copied into global tokens or component APIs without a dedicated follow-up change.
+
+## Pattern Index
+
+| Pattern | File | Use |
+| --- | --- | --- |
+| Navigation TabBar | `design-system/patterns/navigation-tabbar.md` | Bottom navigation geometry, states, icon/text relationship, and shadow evidence. |
+| Card List | `design-system/patterns/card-list.md` | Repeated card/list layout and evidence-backed card styling notes. |
+| Form Section | `design-system/patterns/form-section.md` | Form grouping, text hierarchy, scrolling, and token reading order. |
+
+Single-component details remain governed by `packages/ui/component-registry.json` and each component `schema.json`. Figma evidence for Button, Icon, Avatar, Tag, Checkbox, Radio, and Rate remains in references until a component contract change is explicitly planned.
+
+## Repository Mapping
+
+- `design-system/DESIGN.md` is the only human and Agent design-language entry.
+- `design-system/tokens/source/*.json` is the machine-readable token source.
+- `npm run build:token` merges token source into `design-system/tokens/build/tokens.json`.
+- `packages/theme/src/tokens.ts` and `packages/theme/theme.wxss` are runtime theme artifacts that must stay consistent with token source after token changes.
+- `packages/ui/component-registry.json` owns cross-component reuse, layering, and composition decisions.
+- Each component `schema.json` owns that component's public API.
+
+Compatibility notes:
+
+- `color.brand.text`, `palette.brown.1`, and older brand-support colors remain for historical compatibility.
+- New components should prefer semantic text, background, status, amount, and gender tokens.
+- `color.text.active` remains as a compatibility alias matching `color.text.amount`.
+
+## AI Reading Order
+
+1. Read `design-system/DESIGN.md`.
+2. For exact token values, read `design-system/tokens/source/*.json`.
+3. For raw visual evidence, read `design-system/references/figma-user-client-visual-evidence.md`.
+4. For layout composition, read `design-system/patterns`.
+5. For page structure, read `design-system/schemas/page.schema.json`.
+6. For component capability, read `packages/ui/component-registry.json` and the target component `schema.json`.
+7. For generation instructions, read `design-system/prompts` and `design-system/skills`.
+
+AI output should not bypass schema. Evidence from design boards should be marked as evidence until it is promoted into token source, pattern documentation, schema, or component registry.