codesync-ui-and-state
Architecture for Zustand state management, cross-context extension synchronization, 15+ CSS themes, and modular React UI components.
- License 许可
- Apache-2.0
- 最近更新
- 2026-11-10
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- codesync-ui-and-state
- description
- Architecture for Zustand state management, cross-context extension synchronization, 15+ CSS themes, and modular React UI components.
03 SKILL.md 正文
CodeSync UI, Themes & Reactive State Architecture
Use this skill when developing or modifying popup components, the options page, the theme engine, or the Zustand store in src/popup/, src/options/, src/store/, and src/styles/.
1. Cross-Context Zustand State Synchronization
Because browser extension contexts (Popup UI, Options Page, Background Service Worker) run in completely separate JavaScript runtimes, state mutations must be synchronized across boundaries.
sequenceDiagram
participant UI as Popup / Options (React)
participant Store as Zustand Store
participant Storage as chrome.storage.local
participant Runtime as chrome.runtime Messaging
UI->>Store: updateSettings({ theme: 'dracula' })
Store->>Storage: setLocalStorage({ settings: ... })
Store->>Runtime: sendMessage({ action: 'STATE_CHANGED' })
Runtime-->>Store: Broadcast to all open contexts
Store-->>UI: Re-render with new state
Store Implementation Invariants (src/store/index.ts):
- Singleton Listener Guard:
Prevent multiple
chrome.runtime.onMessageevent listeners from stacking during hot module reloads:let isListenerRegistered = false; if (!isListenerRegistered && typeof chrome !== 'undefined' && chrome.runtime?.onMessage) { isListenerRegistered = true; chrome.runtime.onMessage.addListener((message) => { if (message.action === 'STATE_UPDATED') { useAppStore.getState().initialize(); } }); } - Asynchronous Initializer:
Every UI entrypoint (
Popup.tsx,Options.tsx) callsinitialize()on mount to load encrypted tokens and settings from storage.
2. Dynamic 15+ CSS Theme Engine (src/styles/themes.ts)
CodeSync features a variety of themes (including AMOLED, Dracula, Tokyo Night, Cyberpunk, Matrix, Nord, and Monokai).
Theme Structure
Each theme is defined by a palette of CSS custom property tokens:
export interface Theme {
id: string;
name: string;
colors: {
bgPrimary: string;
bgSecondary: string;
bgTertiary: string;
textPrimary: string;
textSecondary: string;
accent: string;
border: string;
card: string;
};
}
Applying Themes:
Themes are applied to the root document element dynamically:
export function applyTheme(themeId: string): void {
const theme = getThemeById(themeId);
const root = document.documentElement;
Object.entries(theme.colors).forEach(([token, value]) => {
root.style.setProperty(`--color-${token}`, value);
});
}
In Tailwind, CSS variables are mapped via tailwind.config.js:
theme: {
extend: {
colors: {
bgPrimary: 'var(--color-bgPrimary)',
accent: 'var(--color-accent)',
}
}
}
3. Modular Popup Component Hierarchy
The popup UI (src/popup/Popup.tsx) is decomposed into focused, single-responsibility components under src/popup/components/:
Header.tsx: Displays logo, extension version, online status, and theme selector trigger.UpdateBanner.tsx: Renders when a new Chrome Web Store version has downloaded in the background; triggers one-click reload viachrome.runtime.reload().UserProfileCard.tsx: Displays the authenticated GitHub user profile, avatar, and logout action.RepoSelector.tsx: Dropdown for selecting the destination GitHub repository, creating a new repo, and showing solved counts.SyncControl.tsx: Displays the pending commit queue count and provides the manual "Sync Now" trigger button.AuthForm.tsx: Renders GitHub OAuth button and fallback Personal Access Token (PAT) input.Footer.tsx: Navigation links to problem platforms, options page, and documentation.
4. Design Guidelines & Radix Primitives
- Accessibility First:
- Switches use
@radix-ui/react-switchwith associated@radix-ui/react-label. - Modals use accessible backdrop trapping and keyboard escape triggers (
ConfirmModal.tsx).
- Switches use
- Compact Viewport Constraints:
- The Chrome extension popup width is fixed at
w-[360px]tow-[400px]with a maximum height of600px. - Content that exceeds viewport height must use custom scrollbars (
overflow-y-auto).
- The Chrome extension popup width is fixed at
- No Heavy Icon Bundles:
- Icons are centralized in
src/popup/components/Icons.tsxas lightweight, hand-crafted SVG components rather than importing massive full-library bundles (e.g.lucide-reactorreact-icons).
- Icons are centralized in
5. Testing UI State
Test cross-context state hydration and store actions using Vitest:
npm run test -- src/store/__tests__/stateSync.test.ts
04 同仓库更多 Skills
openspec-update-change
Update an OpenSpec change by revising its existing planning artifacts and keeping them coherent with one another. Use when the user wants to revise a change's plan, fold new decisions into it, or reconcile its artifacts after an edit. Never edits code.
openspec-sync-specs
Sync delta specs from a change to main specs. Use when the user wants to update main specs with changes from a delta spec, without archiving the change.
openspec-propose
Propose a new change with all artifacts generated in one step. Use when the user wants to quickly describe what they want to build and get a complete proposal with design, specs, and tasks ready for implementation.
openspec-explore
Enter explore mode - a thinking partner for exploring ideas, investigating problems, and clarifying requirements. Use when the user wants to think through something before or during a change.
openspec-archive-change
Archive a completed change in the experimental workflow. Use when the user wants to finalize and archive a change after implementation is complete.
openspec-apply-change
Implement tasks from an OpenSpec change. Use when the user wants to start implementing, continue implementation, or work through tasks.