sdaduanbilei/cc-haha
1
0
Fork 0
mirror of https://github.com/NanmiCoder/cc-haha synced 2026-07-31 16:33:34 +08:00
Code Issues Packages Projects Releases Wiki Activity
cc-haha/desktop/AGENTS.md
程序员阿江(Relakkes) f91b62f485 docs(desktop): document the component library and its rules 
`components/AGENTS.md` is the reference: what to use for a given need,
where a new component goes, and the style / i18n / a11y / test rules.
`desktop/AGENTS.md` now routes here — the line it replaces ("reuse the
existing desktop design system") named nothing to look up and so was not
an executable instruction for a person or a model.

`docs/component-library-plan.md` keeps the audit evidence and a record of
what actually shipped, including where the plan was wrong.

Two rules earned their own sections because the library broke them
itself:

- Overriding a component's utility with `className` does not reliably
  win. Tailwind sorts same-utility arbitrary values by value and takes
  the last, regardless of the order they were passed. `hoverTone="danger"`
  was a no-op with exactly the two tones it was built for, and its test
  passed because it only asserted the red class was *present*, never that
  the neutral one was gone. Assert that a class prefix appears exactly
  once, and prove it by reverting the fix.
- The library must not compose user-visible English. `SearchField` built
  `Clear ${label}`, which made adopting it an i18n regression for every
  caller that had already translated its clear button. The first repair —
  falling back to `label` — was worse: the input and its clear button
  then shared an accessible name and `getByLabelText` matched both.

Reuse went from 22% to 75% (524 component uses against 179 remaining
native buttons). The remainder are elements that should not be
components: `role="tab"`, `menuitem`, `option`, `treeitem`, `gridcell`,
whole-row and whole-card click targets, drag handles, and the OS
titlebar.
2026-07-26 18:31:34 +08:00

1.3 KiB
Raw Blame History

Desktop Instructions

These rules apply to desktop/ changes in addition to the root instructions.

  • Before adding or editing anything under desktop/src/components/, read desktop/src/components/AGENTS.md. It is the authoritative index of reusable components, the placement rules for new ones, and the required style/i18n/a11y/test conventions. Do not add a component that duplicates one listed there, and do not add new files to components/shared/ or components/common/.
  • Reuse the existing desktop store/API patterns. Use lucide-react for common icons and keep operational UI dense, stable, and readable.
  • Add focused Vitest or Testing Library coverage for UI, store, or API behavior. Run it first, then follow bun run check:impact; desktop product changes normally select bun run check:desktop.
  • Chat transport, WebSocket lifecycle, first-turn runtime selection, reconnect, or session changes also require the offline bun run check:chat-contract when selected.
  • Electron host, sidecar, packaging, or version changes require bun run check:native when selected.
  • Validate user-visible flows in a real browser/desktop session when unit tests cannot prove layout or cross-process behavior, and record the path exercised.
  • localStorage or native settings shape changes require a migration, an old fixture, and bun run check:persistence-upgrade.