You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+18-20Lines changed: 18 additions & 20 deletions
Original file line number
Diff line number
Diff line change
@@ -4,7 +4,7 @@ Spectrum Web Components is a future-looking project to develop Adobe Spectrum de
4
4
5
5
To this end, Spectrum Web Components only targets _modern_, evergreen browsers that fully implement the Custom Elements V1 specification, e.g. Chrome, Firefox, Safari. Polyfills will be avoided as much as possible but documented if necessary.
6
6
7
-
# Requirements
7
+
##Requirements
8
8
9
9
- NodeJS >= 20.0.0
10
10
- Typescript
@@ -17,9 +17,9 @@ To this end, Spectrum Web Components only targets _modern_, evergreen browsers t
17
17
- We support all viewport sizes across supported desktop browsers.
18
18
- While our components are designed to be responsive and mobile-friendly, we do not yet fully support mobile browsers due to limited testing in mobile hardware. We advise testing updates on mobile devices before updating and are happy to address any reported issues.
@@ -33,8 +33,8 @@ Typical development will involve running `yarn storybook`, `yarn test`, and `yar
33
33
34
34
Creating a new component from the command line can be done by running the following:
35
35
36
-
```bash
37
-
$ yarn new-package
36
+
```sh
37
+
yarn new-package
38
38
```
39
39
40
40
This will scaffold your component's required architecture by prompting you for 2 data points - the desired name for your package and the name of the Spectrum CSS asset from which you will be building.
@@ -49,35 +49,35 @@ You can find this information in the [Spectrum CSS GitHub project](https://githu
49
49
50
50
For additional information, please see the [generating components documentation](https://opensource.adobe.com/spectrum-web-components/guides/generating-components) and capturing the value of the package name: `"name": "@spectrum-css/accordion"`. In this example, that name is `accordion`. _Note_ that the project scope `@spectrum-css` is stripped out of the response.
51
51
52
-
# Storybook
52
+
##Storybook
53
53
54
54
Testing & reviewing changes can be done using the Storybook instance. Running `yarn storybook` will spin up a local instance of Storybook, triggering the browser to open at completion. From there you can make changes to your code and the browser will automatically refresh.
55
55
56
56
You can run [Storybook](https://storybook.js.org) through the command:
57
57
58
-
```bash
58
+
```sh
59
59
yarn storybook
60
60
```
61
61
62
62
By default, the resulting site will be available at [http://localhost:8000](http://localhost:8000).
63
63
64
-
# Documentation
64
+
##Documentation
65
65
66
66
The Spectrum Web Components documentation site is available via the following command:
67
67
68
-
```bash
68
+
```sh
69
69
yarn docs:start
70
70
```
71
71
72
72
By default, the resulting site will be available at [http://localhost:8080](http://localhost:8080).
73
73
74
74
In the case that you'd like to serve and test a static build of the documentation from the root directory (`localhost` or otherwise), use:
75
75
76
-
```bash
76
+
```sh
77
77
yarn docs:build
78
78
```
79
79
80
-
# Updating Spectrum CSS
80
+
##Updating Spectrum CSS
81
81
82
82
There are two mechanisms for broadly updating SWC's Spectrum CSS dependencies:
83
83
@@ -87,14 +87,12 @@ There are two mechanisms for broadly updating SWC's Spectrum CSS dependencies:
87
87
We aim to keep Spectrum CSS as current as possible, to track the Spectrum design system closely.
88
88
The `:nonbreaking` variant lets us release patch updates quickly in cases where more work is required to be compatible with 'latest.'
89
89
90
-
# Advanced development
90
+
##Advanced development
91
91
92
92
There are several commands that can be useful in specific scenarios:
93
93
94
-
-`yarn build:clear-cache` to remove previously created artifacts of the `tsc build` process.
95
-
-`yarn spectrum-vars` to ensure that theme files are up-to-date.
96
-
-`yarn process-icons` to make sure that the most recent icons are included.
97
-
-`yarn process-spectrum` to process the spectrum CSS style sources into the individual packages.
94
+
-`yarn build:clean` to remove previously created artifacts of the `tsc build` process.
95
+
-`yarn build:icons` to make sure that the most recent icons are included.
98
96
-`yarn build` to make sure the available JS has been built from the current TS source.
99
97
100
98
## Linting
@@ -105,15 +103,15 @@ The project will be linted on a pre-commit hook, but you can also run the lint s
105
103
106
104
There are downstream issues that can arise from multiple packages in this mono-repo using dependencies with mismatched version strings. By default, changesets will bump version numbers of internal dependencies when the various packages are published and the depended version is pointing to the latest release, which can help to mitigate this issue. Running `yarn lint:versions` will check that all version strings for each dependency match across the repo.
107
105
108
-
`yarn list:versions --fix` will modify the `package.json` files, updating all dependencies to the latest version available in the library —_a potentially dangerous operation_. If this is what you want to do when `yarn lint:versions` discovers mismatched versions, this step can greatly reduce the amount of work to achieve matching version numbers.
106
+
`yarn list:versions --fix` will modify the `package.json` files, updating all dependencies to the latest version available in the library -_a potentially dangerous operation_. If this is what you want to do when `yarn lint:versions` discovers mismatched versions, this step can greatly reduce the amount of work to achieve matching version numbers.
109
107
110
108
## Testing
111
109
112
110
### Unit tests
113
111
114
112
Unit tests are run with [Web Test Runner](https://modern-web.dev/docs/test-runner/overview/) in Playwright using the Chai, Mocha and Sinon helper libraries. These tests can be executed with:
115
113
116
-
```
114
+
```sh
117
115
yarn test
118
116
```
119
117
@@ -127,7 +125,7 @@ Visual regressions are tracked via screenshot testing powered by [`@web/test-run
127
125
128
126
To create a local baseline for comparing your changes to later in the development cycle, use the following:
129
127
130
-
```bash
128
+
```sh
131
129
yarn test:visual:clean # start with a clean slate
132
130
# yarn test:visual:clean:baseline # removes only baseline images
133
131
# yarn test:visual:clean:current # removes only images updated in the most recent test pass
@@ -203,7 +201,7 @@ For a list of component waiting to be implemented, visit our [`missing component
203
201
204
202
The build process compiles `.css` files using PostCSS and wraps them in the `lit-html``css` template tag and writes out a `.css.ts` file for easy import into TypeScript files. This file should not be edited, and is ignored by `.gitignore`, but you may also wish to hide the files in your IDE.
205
203
206
-
# Contributing
204
+
##Contributing
207
205
208
206
We'd be very grateful if you contributed to the project! Check out our [contribution guidelines](CONTRIBUTING.md) for more information.
0 commit comments