Skip to content

Commit 9646ab8

Browse files
wangdicoderwangdicoder
committed
fix: styles
1 parent 2bd02dd commit 9646ab8

71 files changed

Lines changed: 2976 additions & 949 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎REFACTOR_CHECKLIST.md‎

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
# Refactor Checklist
2+
3+
## Phase Checklist
4+
5+
Use this before starting any new phase.
6+
7+
- phase scope is explicit
8+
- entry files are identified
9+
- verification commands are identified
10+
- stop condition is identified
11+
- upstream dependencies are already stable
12+
13+
## Component Checklist
14+
15+
Use this for every component refactor.
16+
17+
- read implementation
18+
- read public types
19+
- read existing tests
20+
- read docs/examples if they exist
21+
- list behavior worth preserving
22+
- list behavior that is inconsistent or fragile
23+
- confirm controlled and uncontrolled state model
24+
- confirm event names and firing points
25+
- confirm container / portal / popup behavior where relevant
26+
- confirm cleanup behavior for timers, listeners, and instances
27+
- add or update focused tests
28+
- run the smallest useful regression set
29+
- stop when the component reaches a stable checkpoint
30+
31+
## Theme And Token Checklist
32+
33+
- JSON sources remain the only editable token source
34+
- theme runtime uses shared resolver logic
35+
- Theme Studio uses the same validation and resolution contract
36+
- preset resolution still works
37+
- browser ESM runtime still works
38+
- registry output still builds
39+
- no alias or migration logic is introduced
40+
- docs only describe canonical token keys
41+
42+
## Popup Stack Checklist
43+
44+
Apply to:
45+
46+
- `Popup`
47+
- `Overlay`
48+
- `Portal`
49+
- `Dropdown`
50+
- `Popover`
51+
- `Tooltip`
52+
- `Modal`
53+
54+
- visibility source is unambiguous
55+
- outside click behavior is defined
56+
- escape behavior is defined if applicable
57+
- popup container behavior is defined
58+
- portal rendering is test-covered
59+
- listeners are removed on cleanup
60+
- timers are removed on cleanup
61+
- popper / instance objects are destroyed on cleanup
62+
63+
## Before Moving Up A Layer
64+
65+
- current layer tests pass
66+
- no known runtime regression remains in the current layer
67+
- docs / Theme Studio still render
68+
- there is a clear summary of what changed
69+
- next component group is identified

‎THEME_TOKEN_REFACTOR_ROADMAP.md‎

Lines changed: 228 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,228 @@
1+
# Theme And Token Refactor Roadmap
2+
3+
## Goal
4+
5+
Build the next major version of Tiny Design theming with one rule:
6+
7+
- only the new token model is supported
8+
9+
This roadmap assumes a breaking release. We are not preserving legacy token names, legacy theme keys, or parallel token systems.
10+
11+
## Upgrade Policy
12+
13+
The next major version follows these constraints:
14+
15+
- `packages/tokens/source/**.json` is the only source of truth
16+
- runtime, docs, Theme Studio, and React all consume the same theme contract
17+
- old SCSS-era token names are removed, not translated
18+
- old API aliases are removed, not dual-supported
19+
- documentation only describes the new contract
20+
21+
## Current Progress
22+
23+
Completed:
24+
25+
- tokens runtime resolution is shared across `@tiny-design/tokens`, `@tiny-design/react`, and Theme Studio
26+
- preset theme resolution with `extends`
27+
- browser-safe ESM runtime for docs and Theme Studio
28+
- `ConfigProvider` integrated with token resolution
29+
- `Popup / Overlay / Portal` bottom-layer cleanup and tests
30+
31+
In progress:
32+
33+
- removing alias and migration logic that was temporarily added during the transition
34+
- tightening execution checklists for the next component phases
35+
36+
## Target Architecture
37+
38+
### `@tiny-design/tokens`
39+
40+
Owns:
41+
42+
- semantic token source
43+
- component token source
44+
- theme documents
45+
- schema
46+
- registry generation
47+
- preset generation
48+
- theme validation
49+
- theme resolution
50+
- typed token exports
51+
52+
Does not own:
53+
54+
- legacy token aliases
55+
- migration shims
56+
- dual-format theme support
57+
58+
### `@tiny-design/react`
59+
60+
Owns:
61+
62+
- scoped CSS variable application
63+
- `ConfigProvider` theme integration
64+
- container / popup scoping behavior
65+
- component token consumption discipline
66+
67+
Does not own:
68+
69+
- ad-hoc token flattening
70+
- custom theme parsing separate from `@tiny-design/tokens`
71+
72+
### Theme Studio / Docs
73+
74+
Own:
75+
76+
- authoring UI
77+
- preview and export flows
78+
- token browsing and documentation
79+
80+
Must consume:
81+
82+
- the same validation and resolution contract as runtime
83+
84+
## Execution Phases
85+
86+
### Phase 1: Tokens Core
87+
88+
Objectives:
89+
90+
- keep JSON as the only editable token source
91+
- keep presets and schema aligned
92+
- validate theme documents against registry
93+
- remove alias and migration support from runtime and build outputs
94+
95+
Acceptance:
96+
97+
- no runtime alias translation
98+
- no generated alias metadata
99+
- new token keys are the only supported authored keys
100+
101+
### Phase 2: React Theme Integration
102+
103+
Objectives:
104+
105+
- keep `ConfigProvider` on top of `resolveTheme`
106+
- standardize theme mode resolution
107+
- keep scoped CSS variable injection stable
108+
109+
Acceptance:
110+
111+
- React runtime does not implement its own theme parser
112+
- local provider scoping remains stable
113+
114+
### Phase 3: Bottom-Layer Popup Infrastructure
115+
116+
Scope:
117+
118+
- `Popup`
119+
- `Overlay`
120+
- `Portal`
121+
122+
Objectives:
123+
124+
- stabilize visibility flow
125+
- stabilize popup container usage
126+
- clean up event listener lifecycle
127+
- preserve existing good behavior
128+
129+
Acceptance:
130+
131+
- bottom-layer popup tests pass
132+
- no listener leaks in current flows
133+
134+
### Phase 4: First-Layer Popup Consumers
135+
136+
Scope:
137+
138+
- `Dropdown`
139+
- `Popover`
140+
- `Tooltip`
141+
- `Modal`
142+
143+
Objectives:
144+
145+
- reuse the cleaned popup stack
146+
- remove duplicated open/close mechanics
147+
- keep API changes deliberate and minimal
148+
149+
Acceptance:
150+
151+
- each component has controlled/uncontrolled coverage
152+
- outside click / escape / focus behavior is defined and tested
153+
154+
### Phase 5: Form And Selection Core
155+
156+
Scope:
157+
158+
- `Form`
159+
- `Select`
160+
- `AutoComplete`
161+
- `DatePicker`
162+
- `TimePicker`
163+
164+
Objectives:
165+
166+
- align state models
167+
- align popup usage
168+
- align token consumption
169+
170+
Acceptance:
171+
172+
- no type/runtime contract mismatch
173+
- no parallel internal state paths for the same behavior
174+
175+
### Phase 6: Token Coverage Expansion
176+
177+
Objectives:
178+
179+
- define missing component namespaces
180+
- document namespace reuse explicitly
181+
- replace remaining hardcoded visual values where tokens should own them
182+
183+
Priority targets:
184+
185+
- `dropdown`
186+
- `overlay`
187+
- `date-picker`
188+
- `time-picker`
189+
- `auto-complete`
190+
- `modal`
191+
- `tooltip`
192+
- `popover`
193+
194+
Acceptance:
195+
196+
- each production component has explicit token ownership
197+
198+
### Phase 7: Quality Platform
199+
200+
Objectives:
201+
202+
- interaction tests for complex components
203+
- a11y checks for core flows
204+
- visual regression for key docs examples
205+
206+
Acceptance:
207+
208+
- complex components have behavior coverage, not just snapshots
209+
210+
## Working Rules
211+
212+
These rules apply to every phase:
213+
214+
- read implementation, types, tests, and docs before editing
215+
- keep existing good behavior
216+
- remove only the parts that are inconsistent, redundant, or unstable
217+
- do not expand scope upward until the current layer is stable
218+
- stop at a clear verification point before moving to the next component group
219+
220+
## Immediate Next Queue
221+
222+
1. Finish removing temporary alias/migration support from `packages/tokens`
223+
2. Keep Theme Studio aligned with the strict new token contract
224+
3. Start the first-layer popup consumers:
225+
- `Dropdown`
226+
- `Popover`
227+
- `Tooltip`
228+
- `Modal`

‎apps/docs/src/containers/theme-studio/index.tsx‎

Lines changed: 9 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
import React, { useEffect, useMemo, useState } from 'react';
22
import type { ThemeDocument } from '@tiny-design/react';
3+
import { validateThemeDocument } from '@tiny-design/tokens/validate-theme';
34
import {
45
Button,
56
ConfigProvider,
@@ -116,10 +117,16 @@ const ThemeStudioPage = (): React.ReactElement => {
116117
const handleImport = () => {
117118
try {
118119
const parsed = JSON.parse(importText) as ThemeDocument;
119-
setDraft(buildDraftFromThemeDocument(parsed));
120+
const validation = validateThemeDocument(parsed);
121+
if (!validation.valid) {
122+
setImportError(validation.errors.join('\n'));
123+
return;
124+
}
125+
126+
setDraft(buildDraftFromThemeDocument(validation.normalizedDocument as ThemeDocument));
120127
setImportVisible(false);
121128
setImportError(null);
122-
setStatus('Imported theme document');
129+
setStatus(validation.warnings.length > 0 ? 'Imported theme document with validation warnings' : 'Imported theme document');
123130
} catch {
124131
setImportError('Invalid theme document JSON');
125132
}

0 commit comments

Comments
 (0)