77 lines
3.6 KiB
Markdown
77 lines
3.6 KiB
Markdown
# Repository Instructions
|
|
|
|
## SHD design-system maintenance
|
|
|
|
Treat `docs/DESIGN_SYSTEM.md` and the shared tokens and patterns in `src/app.css`
|
|
as maintained parts of the product.
|
|
|
|
Whenever a change makes a significant visual or interaction-design decision,
|
|
update the design system in the same change. This includes:
|
|
|
|
- introducing or changing colors, typography, spacing, borders, elevation, or motion;
|
|
- creating a new reusable layout, navigation, table, editor, form, card, status, or feedback pattern;
|
|
- materially changing dashboard density, hierarchy, responsive behavior, or accessibility behavior;
|
|
- changing the semantic meaning of an existing visual state;
|
|
- establishing a pattern that future pages or components should follow.
|
|
|
|
For significant design changes:
|
|
|
|
1. Reuse or extend the CSS custom properties in `src/app.css`; do not scatter
|
|
near-duplicate hard-coded values throughout new components.
|
|
2. Update `docs/DESIGN_SYSTEM.md` with the new or revised rule, token, pattern,
|
|
usage guidance, and responsive or accessibility considerations.
|
|
3. Refactor repeated UI into a reusable component when that makes the pattern
|
|
clearer and reduces divergence.
|
|
4. Preserve the SHD design principles: tactical but restrained, data-first,
|
|
square and engineered, orange reserved for action and emphasis, and explicit
|
|
textual state indicators.
|
|
5. Verify hover, pressed, focus-visible, pending, disabled, error, success, and
|
|
reduced-motion behavior where applicable.
|
|
6. Run `npm run check` and `npm run build` before completing the change.
|
|
|
|
Minor alignment fixes, isolated bug fixes, and corrections that do not introduce
|
|
or revise a reusable design decision do not require a documentation update.
|
|
|
|
If uncertain whether a visual change is significant, update the design system.
|
|
|
|
## ISAC editor lifecycle
|
|
|
|
All ISAC data-management editors must follow the same successful-save behavior:
|
|
|
|
1. Saving an edit to an existing record closes the editor and returns the user
|
|
to the registry.
|
|
2. Saving a newly added record keeps the editor open with a fresh blank record
|
|
so consecutive data entry remains fast.
|
|
3. Validation errors keep the editor open and preserve the entered values.
|
|
4. Server actions must return the add/edit mode and a unique result token;
|
|
client-side reactive handling must consume each token only once to avoid
|
|
repeated state updates.
|
|
|
|
Apply this convention whenever an ISAC editor is added or materially changed.
|
|
|
|
## Database preservation
|
|
|
|
Development data is valuable and may be entered by non-technical contributors.
|
|
Treat embedded database files as persistent user data, not disposable build
|
|
artifacts.
|
|
|
|
Before deleting, replacing, recreating, renaming, or destructively migrating a
|
|
database—and before any major schema change—create a timestamped JSON backup
|
|
with `npm run db:backup`.
|
|
|
|
Database work must follow these rules:
|
|
|
|
1. Confirm which environment and exact database path are in scope.
|
|
2. Stop processes that hold the embedded database lock before backup or restore.
|
|
3. Create and verify a JSON backup before destructive work.
|
|
4. Never overwrite or delete the only available backup.
|
|
5. Keep backups out of Git; they can contain user records and password hashes.
|
|
6. Prefer additive, repeatable schema migrations over database recreation.
|
|
7. After a restore, run the schema migration and verify record counts and
|
|
critical entities before resuming data entry.
|
|
8. Report the backup path when completing database-destructive work.
|
|
|
|
Use `npm run db:restore -- <backup-file>` only with an empty, migrated target
|
|
database. The restore script intentionally refuses to merge into a populated
|
|
database.
|