@arbor-education/design-system.components 3.0.1 → 3.0.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +6 -0
- package/package.json +1 -1
- package/src/docs/Contributing.mdx +32 -11
- package/src/docs/UsingComponents.mdx +8 -6
- package/src/docs/Welcome.mdx +4 -4
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,11 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 3.0.2
|
|
4
|
+
|
|
5
|
+
### Patch Changes
|
|
6
|
+
|
|
7
|
+
- [#250](https://github.com/arbor-education/design-system.components/pull/250) [`f7f308e`](https://github.com/arbor-education/design-system.components/commit/f7f308eae96d2002499afc26498983bb619aa314) Thanks [@rickbairstow](https://github.com/rickbairstow)! - MIS-74501 Update Storybook getting started documentation
|
|
8
|
+
|
|
3
9
|
## 3.0.1
|
|
4
10
|
|
|
5
11
|
### Patch Changes
|
package/package.json
CHANGED
|
@@ -4,15 +4,36 @@ import { Meta } from '@storybook/addon-docs/blocks';
|
|
|
4
4
|
|
|
5
5
|
# Contributing to the Design System
|
|
6
6
|
|
|
7
|
-
←
|
|
7
|
+
← <a href="/?path=/docs/getting-started-welcome--docs">Back to Welcome</a>
|
|
8
8
|
|
|
9
|
-
This guide is for developers working on the design system itself — adding new components, fixing bugs, or improving docs. If you're just looking to use components in a product, see
|
|
9
|
+
This guide is for developers working on the design system itself — adding new components, fixing bugs, or improving docs. If you're just looking to use components in a product, see <a href="/?path=/docs/getting-started-using-the-components--docs">Using the Components</a>.
|
|
10
|
+
|
|
11
|
+
---
|
|
12
|
+
|
|
13
|
+
## Design System rules
|
|
14
|
+
|
|
15
|
+
- **Don't override design system styles — use tokens.** If a token or component doesn't fit your case, come and talk to us rather than patching around it with custom CSS.
|
|
16
|
+
- **Talk to us before contributing a new component.** It may already exist, or the design may need revisiting first.
|
|
17
|
+
|
|
18
|
+
Questions or contributions go in <a href="https://arbor-education.slack.com/archives/C0BJU1K3HH9" target="_blank" rel="noopener noreferrer">#design-system-help</a>. Full context and the rest of the rules live on <a href="https://orchard.atlassian.net/wiki/spaces/AG/pages/2682749029/Design+System+Start+Here" target="_blank" rel="noopener noreferrer">Design System: Start Here</a>.
|
|
19
|
+
|
|
20
|
+
---
|
|
21
|
+
|
|
22
|
+
## Before building a new component
|
|
23
|
+
|
|
24
|
+
If you're adding a genuinely new component, variant, or pattern — as opposed to fixing a bug or improving docs — check with the team first:
|
|
25
|
+
|
|
26
|
+
1. Check whether an existing component or pattern already solves the problem.
|
|
27
|
+
2. Raise it via the contribution workflow in <a href="https://arbor-education.slack.com/archives/C0BJU1K3HH9" target="_blank" rel="noopener noreferrer">#design-system-help</a>, providing the info it sets out — the problem, the user need, your proposed solution, and what existing patterns you've considered.
|
|
28
|
+
3. Design and Front End review async and agree the direction before you start building.
|
|
29
|
+
|
|
30
|
+
This avoids wasted effort building something that already exists or doesn't fit the system. Full details in <a href="https://orchard.atlassian.net/wiki/spaces/AG/pages/2724429855/Design+System+Design+System+Contribution+Process" target="_blank" rel="noopener noreferrer">Design System Contribution Process</a>.
|
|
10
31
|
|
|
11
32
|
---
|
|
12
33
|
|
|
13
34
|
## Local setup
|
|
14
35
|
|
|
15
|
-
**Prerequisites:**
|
|
36
|
+
**Prerequisites:** <a href="https://github.com/nvm-sh/nvm" target="_blank" rel="noopener noreferrer">nvm</a> and <a href="https://classic.yarnpkg.com/lang/en/docs/install/" target="_blank" rel="noopener noreferrer">yarn</a>
|
|
16
37
|
|
|
17
38
|
```bash
|
|
18
39
|
nvm use
|
|
@@ -133,7 +154,7 @@ This is the most important principle. **Empower consumers, don't constrain them.
|
|
|
133
154
|
|
|
134
155
|
Rather than encoding every possible use case into a component's internals, expose the right props and hooks to let the consumer drive behaviour. When you're unsure whether to handle something inside the component or leave it to the consumer, default to leaving it to the consumer.
|
|
135
156
|
|
|
136
|
-
The Table component is the clearest example of this in practice. Rather than building a full data-grid from scratch, Table is a thin wrapper over
|
|
157
|
+
The Table component is the clearest example of this in practice. Rather than building a full data-grid from scratch, Table is a thin wrapper over <a href="https://www.ag-grid.com/" target="_blank" rel="noopener noreferrer">AG Grid</a> — it applies Arbor's defaults and design tokens, then gets out of the way. Consumers get the full power of AG Grid's API directly. We don't abstract it away.
|
|
137
158
|
|
|
138
159
|
Ask yourself: *"Am I solving a problem that every consumer will always have, or am I solving one specific consumer's problem?"* Only the former belongs in the component.
|
|
139
160
|
|
|
@@ -251,15 +272,15 @@ Never push directly to `main` — all work goes through a branch and PR.
|
|
|
251
272
|
- **Every PR requires a changeset.** These should be generated by running `yarn changeset`, which takes you through a prompt to specify the change level and to give a brief description of your change
|
|
252
273
|
- **Do not let an AI create a changeset file for you.** AI Agents have a propensity to directly write their own changeset files, which often hallucinate the structure of the files, or the name of the changeset project, which can result in stray changeset files not being added to the changelog on releases. Generate **all** changeset files via `yarn changeset`.
|
|
253
274
|
- **Do not use backticks or quotes in your changeset description** - these break the release automation
|
|
254
|
-
- We follow
|
|
275
|
+
- We follow <a href="https://semver.org/" target="_blank" rel="noopener noreferrer">semantic versioning</a>: **major** for breaking changes, **minor** for new backwards-compatible functionality, **patch** for backwards-compatible fixes and other non-breaking changes.
|
|
255
276
|
|
|
256
|
-
For the full details and the reasoning behind these rules, see
|
|
277
|
+
For the full details and the reasoning behind these rules, see <a href="https://github.com/arbor-education/design-system.components/blob/main/CONTRIBUTING.md" target="_blank" rel="noopener noreferrer">CONTRIBUTING.md</a> on GitHub.
|
|
257
278
|
|
|
258
279
|
---
|
|
259
280
|
|
|
260
281
|
## Local development with a consumer project
|
|
261
282
|
|
|
262
|
-
The library uses
|
|
283
|
+
The library uses <a href="https://github.com/wclr/yalc" target="_blank" rel="noopener noreferrer">Yalc</a> for local linking to consumer projects.
|
|
263
284
|
|
|
264
285
|
```bash
|
|
265
286
|
# Install Yalc globally (first time only)
|
|
@@ -284,7 +305,7 @@ yarn watch
|
|
|
284
305
|
|
|
285
306
|
## Useful links
|
|
286
307
|
|
|
287
|
-
-
|
|
288
|
-
-
|
|
289
|
-
-
|
|
290
|
-
-
|
|
308
|
+
- <a href="https://github.com/arbor-education/design-system.components" target="_blank" rel="noopener noreferrer">GitHub repository</a>
|
|
309
|
+
- <a href="https://github.com/arbor-education/design-system.components/blob/main/CONTRIBUTING.md" target="_blank" rel="noopener noreferrer">CONTRIBUTING.md</a> — the full contribution guide
|
|
310
|
+
- <a href="https://www.npmjs.com/package/@arbor-education/design-system.components" target="_blank" rel="noopener noreferrer">NPM package</a>
|
|
311
|
+
- <a href="https://orchard.atlassian.net/wiki/spaces/AG/pages/2575958235/AI+personalities" target="_blank" rel="noopener noreferrer">AI personalities (FRENDS)</a> — opt-in personality skills for Claude Code / Cursor and why we don't default them in repos
|
|
@@ -4,9 +4,9 @@ import { Meta } from '@storybook/addon-docs/blocks';
|
|
|
4
4
|
|
|
5
5
|
# Using the Components
|
|
6
6
|
|
|
7
|
-
←
|
|
7
|
+
← <a href="/?path=/docs/getting-started-welcome--docs">Back to Welcome</a>
|
|
8
8
|
|
|
9
|
-
This guide covers how to get Arbor Design System components into your project. If you're looking to contribute to the design system itself, head over to
|
|
9
|
+
This guide covers how to get Arbor Design System components into your project. If you're looking to contribute to the design system itself, head over to <a href="/?path=/docs/getting-started-contributing--docs">Contributing</a>.
|
|
10
10
|
|
|
11
11
|
---
|
|
12
12
|
|
|
@@ -82,12 +82,14 @@ Not sure which component to reach for? A few tips:
|
|
|
82
82
|
|
|
83
83
|
- Browse the sidebar — components are listed alphabetically under **Components**, with complex ones (Table, FormField, Modals) having nested sub-sections
|
|
84
84
|
- Check the **When to use** and **When not to use** sections on each component's Docs page — they'll point you in the right direction
|
|
85
|
-
- If nothing fits, drop a message in
|
|
85
|
+
- If nothing fits, drop a message in <a href="https://arbor-education.slack.com/archives/C0BJU1K3HH9" target="_blank" rel="noopener noreferrer">#design-system-help</a> — the team can point you in the right direction
|
|
86
|
+
- Thinking of building a new one? See the "Before building a new component" section of the <a href="/?path=/docs/getting-started-contributing--docs">Contributing</a> guide first
|
|
87
|
+
- For general frontend issues unrelated to the design system, use <a href="https://arbor-education.slack.com/archives/C08AZT15KH7" target="_blank" rel="noopener noreferrer">#frontend-support</a> instead
|
|
86
88
|
|
|
87
89
|
---
|
|
88
90
|
|
|
89
91
|
## Useful links
|
|
90
92
|
|
|
91
|
-
-
|
|
92
|
-
-
|
|
93
|
-
-
|
|
93
|
+
- <a href="https://www.npmjs.com/package/@arbor-education/design-system.components" target="_blank" rel="noopener noreferrer">NPM package</a>
|
|
94
|
+
- <a href="https://github.com/arbor-education/design-system.components" target="_blank" rel="noopener noreferrer">GitHub repository</a>
|
|
95
|
+
- <a href="https://orchard.atlassian.net/wiki/spaces/AG/pages/2682749029/Design+System+Start+Here" target="_blank" rel="noopener noreferrer">Design System: Start Here (Confluence)</a>
|
package/src/docs/Welcome.mdx
CHANGED
|
@@ -72,7 +72,7 @@ Here's how to get the most out of it:
|
|
|
72
72
|
|
|
73
73
|
## Useful links
|
|
74
74
|
|
|
75
|
-
-
|
|
76
|
-
-
|
|
77
|
-
-
|
|
78
|
-
-
|
|
75
|
+
- <a href="https://www.npmjs.com/package/@arbor-education/design-system.components" target="_blank" rel="noopener noreferrer">NPM package</a> — `@arbor-education/design-system.components`
|
|
76
|
+
- <a href="https://github.com/arbor-education/design-system.components" target="_blank" rel="noopener noreferrer">GitHub repository</a>
|
|
77
|
+
- <a href="https://www.figma.com/file/2GNa44f89PatHEF49n5DaO/Arbor-DSM?node-id=1%3A2" target="_blank" rel="noopener noreferrer">Figma design system</a>
|
|
78
|
+
- <a href="https://orchard.atlassian.net/wiki/spaces/AG/pages/2682749029/Design+System+Start+Here" target="_blank" rel="noopener noreferrer">Design System: Start Here (Confluence)</a>
|