Skip to content

Commit 6a6063b

Browse files
marissahuysentruytmarissahuysentruyt
committed
docs: change content to index and routing
1 parent 1636fd4 commit 6a6063b

File tree

7 files changed

+102
-1026
lines changed

7 files changed

+102
-1026
lines changed

‎1st-gen/AGENTS.md‎

Lines changed: 16 additions & 136 deletions
Original file line numberDiff line numberDiff line change
@@ -1,145 +1,25 @@
1-
# 1st-Gen Package — Agent Guide
1+
# 1st-gen
22

3-
**This is the past.** 1st-gen is being actively migrated to 2nd-gen and will be deprecated once that migration is complete. Do not add new features or components here. Bug fixes and migration work are the only reasons to make changes in this directory.
3+
**This is the past.** 1st-gen is being actively migrated to 2nd-gen and will be deprecated once that migration is complete. Do not add new features. Bug fixes and migration work only.
44

5-
If you are working on a component that exists in both generations, prefer making logic changes in `2nd-gen/packages/core/` so both generations benefit. If you find yourself adding something that only exists in 1st-gen, ask whether it belongs in core instead.
5+
If a change belongs in both generations, make it in `2nd-gen/packages/core/` so both benefit.
66

7-
See [`2nd-gen/AGENTS.md`](../2nd-gen/AGENTS.md) for the future direction, and the [migration workstream docs](../CONTRIBUTOR-DOCS/03_project-planning/02_workstreams/02_2nd-gen-component-migration/README.md) for the component-by-component migration workflow.
8-
9-
---
10-
11-
This is the 1st-generation Spectrum Web Components library — 69 component packages built on Lit, organized as a Yarn workspaces monorepo. Components here extend abstract base classes from `@spectrum-web-components/core` (the 2nd-gen core package) for shared logic, then add 1st-gen styling and rendering on top.
12-
13-
---
14-
15-
## Directory structure
7+
## Structure
168

179
```text
1810
1st-gen/
19-
├── packages/ # 69 component packages (badge, button, accordion, ...)
20-
├── tools/ # Shared internal tooling (base, theme, styles, reactive-controllers, ...)
21-
├── projects/ # Non-component workspaces (documentation, VRT, story decorator, types)
22-
├── storybook/ # Storybook configuration (webpack5)
23-
├── test/ # Global test infrastructure
24-
└── scripts/ # Build and utility scripts
25-
```
26-
27-
**Components always live in `packages/`.** Tools and projects are not components — do not look for component logic there.
28-
29-
---
30-
31-
## How to find a component
32-
33-
Every component is a self-contained package under `packages/<component-name>/`:
34-
35-
```text
36-
packages/badge/
37-
├── src/
38-
│ ├── Badge.ts # Component class (the main file to read/edit)
39-
│ ├── index.ts # Export entry point
40-
│ ├── badge.css # Component styles
41-
│ └── spectrum-badge.css # Spectrum CSS base
42-
├── stories/
43-
│ └── badge.stories.ts # Storybook stories
44-
├── test/
45-
│ ├── badge.test.ts # Unit tests
46-
│ └── badge.a11y.spec.ts # Accessibility snapshot tests
47-
├── sp-badge.ts # Custom element registration
48-
└── package.json
11+
├── packages/ # 69 component packages + 10 shared tool packages
12+
├── tools/ # Shared base classes, mixins, reactive controllers
13+
├── projects/ # Non-component workspaces (docs, VRT, templates, types)
14+
├── storybook/ # Storybook configuration
15+
├── test/ # Global test infrastructure
16+
└── scripts/ # Build and utility scripts
4917
```
5018

51-
The component class is always in `src/<ComponentName>.ts`. More complex packages may have multiple classes (e.g. `Accordion.ts` + `AccordionItem.ts`, `Button.ts` + `ButtonBase.ts`).
52-
53-
---
54-
55-
## Relationship to 2nd-gen core
56-
57-
1st-gen component classes **extend base classes from `@spectrum-web-components/core`** — the 2nd-gen core package. Core provides shared properties, types, validation, and mixins. 1st-gen adds its own `render()`, CSS, and S1-specific variants.
58-
59-
```typescript
60-
// packages/badge/src/Badge.ts
61-
import {
62-
BadgeBase,
63-
BADGE_VARIANTS_S1,
64-
BADGE_VARIANTS_COLOR_S1,
65-
type BadgeVariantS1,
66-
} from '@spectrum-web-components/core/components/badge';
67-
68-
export class Badge extends BadgeBase {
69-
static override readonly VARIANTS = BADGE_VARIANTS_S1;
70-
static override readonly VARIANTS_COLOR = BADGE_VARIANTS_COLOR_S1;
71-
72-
@property({ type: String, reflect: true })
73-
public override variant: BadgeVariantS1 = 'informative';
74-
75-
public static override get styles(): CSSResultArray {
76-
return [styles];
77-
}
78-
79-
protected override render(): TemplateResult { ... }
80-
}
81-
```
82-
83-
The path alias `@spectrum-web-components/core/*` resolves to `../2nd-gen/packages/core/*/dist` via `tsconfig.json`. **Core must be built before 1st-gen can compile.** The `prebuild` script handles this automatically.
84-
85-
**What stays in core vs 1st-gen:**
86-
87-
| Concern | Where it lives |
88-
| ----------------------------------------- | ------------------------------------------------------- |
89-
| Base class, shared properties, validation | `2nd-gen/packages/core/` |
90-
| S1-specific variant lists and types | `core/components/<name>/Component.types.ts` (S1 arrays) |
91-
| 1st-gen `render()` and CSS | `1st-gen/packages/<name>/src/` |
92-
| Element registration (`sp-<name>`) | `1st-gen/packages/<name>/sp-<name>.ts` |
93-
94-
---
95-
96-
## Build system
97-
98-
1st-gen uses **Yarn workspaces v4** + **Wireit** for build orchestration.
99-
100-
```sh
101-
yarn build # Compile TypeScript + generate types
102-
yarn build:css # Process .css → .css.ts (Lit css`` wrappers)
103-
yarn start # Run core in dev mode + Storybook on port 8080
104-
```
105-
106-
**Build pipeline:** CSS build → TypeScript (esbuild, fast) → Type declarations (tsc)
107-
108-
CSS files are processed by PostCSS into `.css.ts` files that wrap styles in Lit's `css` template tag. You will see `import styles from './badge.css.js'` in component classes — this refers to the generated `.css.ts` output.
109-
110-
**Important:** 2nd-gen core must be built first. Run `yarn build` in `2nd-gen/packages/core/` if core is out of date.
111-
112-
---
113-
114-
## Testing
115-
116-
```sh
117-
yarn test # Unit tests via Web Test Runner (Playwright — Chrome, Firefox, WebKit)
118-
yarn test:visual # Visual regression tests
119-
```
120-
121-
| File | What it tests |
122-
| --------------------------------- | ---------------------------------------------------------------------- |
123-
| `test/<component>.test.ts` | Unit tests — DOM, properties, events (Mocha + Chai + @open-wc/testing) |
124-
| `test/<component>.a11y.spec.ts` | Accessibility tree snapshots |
125-
| `test/<component>-memory.test.ts` | Memory leak detection |
126-
| `test/benchmark/` | Performance benchmarks (Tachometer) |
127-
128-
---
129-
130-
## Storybook
131-
132-
```sh
133-
yarn storybook # Start Storybook on port 8080
134-
```
135-
136-
Stories live in `packages/<component>/stories/<component>.stories.ts`. Storybook scans `packages/*/stories/*.stories.js` automatically — no manual registration needed.
137-
138-
---
139-
140-
## Key conventions
19+
## Where to look next
14120

142-
- **Element tag names:** `sp-<component>` (e.g. `sp-badge`, `sp-button`)
143-
- **Package names:** `@spectrum-web-components/<component>`
144-
- **CSS:** Source `.css` files are processed to `.css.ts` at build time — edit the `.css` source, not the generated file
145-
- **Deprecated exports:** Standalone type and const exports from 1st-gen packages are deprecated in favor of static properties on the element class (e.g. `Badge.VARIANTS` instead of importing `BADGE_VARIANTS_S1` directly). New code should follow this pattern.
21+
- [`packages/AGENTS.md`](./packages/AGENTS.md) — component and tool packages
22+
- [`tools/AGENTS.md`](./tools/AGENTS.md) — shared tooling
23+
- [`projects/AGENTS.md`](./projects/AGENTS.md) — non-component workspaces
24+
- [`2nd-gen/AGENTS.md`](../2nd-gen/AGENTS.md) — the future direction
25+
- [Migration workstream docs](../CONTRIBUTOR-DOCS/03_project-planning/02_workstreams/02_2nd-gen-component-migration/README.md)

0 commit comments

Comments
 (0)