UNPKG

@spark-web/design-system

Version:

--- title: Design System ---

108 lines (77 loc) • 5.45 kB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
# Pattern library — surface registry and classifier This file is the SINGLE SOURCE OF TRUTH for which surfaces exist, how to classify a task into a surface, and which pattern file to read for a feature type. Other documents must link here — never copy these tables. When an agent receives a PRD or feature brief, it must read this file first, before any component or pattern documentation. --- ## Step 1 — Identify the surface The design system supports exactly three surfaces: | Signal in PRD | Surface | Status | | -------------------------------------------------------------------------------- | -------------- | --------- | | "admin", "admin portal", "internal", "back office", "ops", "manage", "dashboard" | internal-admin | Defined | | "vendor", "vendor portal", "accreditation", "installer", "partner" | vendor-admin | Defined | | "website", "marketing", "landing page", "public", "brighte.com.au" | website | (planned) | Classify by who uses the screen, not by which words appear most: internal Brighte staff operating the business → internal-admin; vendors/installers signing in to manage their own work → vendor-admin; unauthenticated public visitors → website. If signals from more than one row match and the audience is unclear, ask for clarification — never pick a surface by signal count. If the surface cannot be determined from the PRD, ask for clarification before proceeding. Do not assume. If a PRD matches a surface marked (planned), flag to the team that the surface rules do not exist yet and do not proceed with building until they do. --- ## Step 2 — Read the rules for that surface | Surface | Rules location | | -------------- | ------------------------------------------------------------------------- | | internal-admin | `node_modules/@spark-web/design-system/patterns/internal-admin/CLAUDE.md` | | vendor-admin | `node_modules/@spark-web/design-system/patterns/vendor-admin/CLAUDE.md` | | website | (planned) — flag to the team | Read the surface rules file in full before reading any component documentation. Surface rules take precedence over component rules. --- ## Step 3 — Read the pattern for the feature type Use the table for the surface you classified in Step 1. ### internal-admin | Feature type | Pattern file | | ---------------------------- | -------------------------------------------------------------------------------------- | | List of records with actions | `node_modules/@spark-web/design-system/patterns/internal-admin/list-page.md` | | Record detail view | `node_modules/@spark-web/design-system/patterns/internal-admin/detail-page.md` | | Create or edit a record | `node_modules/@spark-web/design-system/patterns/internal-admin/form-page.md` (planned) | ### vendor-admin | Feature type | Pattern file | | ------------------------------------ | -------------------------------------------------------------------------- | | Vendor list of records with actions | `node_modules/@spark-web/design-system/patterns/vendor-admin/list-page.md` | | Vendor create / edit / settings form | `node_modules/@spark-web/design-system/patterns/vendor-admin/form-page.md` | | Vendor record detail view | (planned) | | Vendor dashboard | `node_modules/@spark-web/design-system/patterns/vendor-admin/dashboard.md` | | Vendor tabbed screen | (planned) | If no pattern file exists yet for the feature type, use the surface rules and component documentation to make the best decision, and flag that a pattern file should be created for this feature type. --- ## Consumer overlays Pattern files describe the design-system-canonical implementation using `@spark-web/*` components only. Where a specific consuming repo must substitute a local component (legacy constraints), that substitution lives in a per-consumer overlay file in the surface directory, named after the consumer — e.g. `node_modules/@spark-web/design-system/patterns/internal-admin/portal-hub.md` for portal-hub on internal-admin, and `node_modules/@spark-web/design-system/patterns/vendor-admin/vendor-portal.md` for vendor-portal on vendor-admin. Reading rule: after reading a pattern file, check the surface directory for an overlay matching the repo you are working in and apply its substitutions. An overlay overrides the pattern only where it explicitly says so. --- ## Reading order for any build task Full reading order (including how to read component docs): see `node_modules/@spark-web/design-system/CLAUDE.md`. This file owns the Step 1-3 classification tables above. Pattern files are decision trees — always read them in full. --- ## Maintaining this file When a surface or pattern file is added, renamed, or removed under `patterns/`, update the tables above in the same commit. `yarn check:agent-docs` fails CI if these tables and the filesystem disagree.