@allons-y/webc-oss-site 0.1.0-beta.1 → 0.1.0-beta.3
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/README.md +22 -17
- package/llms.txt +70 -0
- package/package.json +3 -2
package/README.md
CHANGED
|
@@ -1,9 +1,11 @@
|
|
|
1
1
|
# @allons-y/webc-oss-site
|
|
2
2
|
|
|
3
|
-
The OSS site theme for [Norn](https://github.com/allonsy-studio/webc-resources#readme) sites: the Allons-y Studio brand tokens, the self-hosted fonts,
|
|
3
|
+
The OSS site theme for [Norn](https://github.com/allonsy-studio/webc-resources#readme) sites: the Allons-y Studio brand tokens, the self-hosted fonts, & the locked OSS banner, call to action, & footer credit. Everything generic, the layouts & the data builders included, lives in [`@allons-y/webc-patterns`](https://github.com/allonsy-studio/webc-resources/tree/main/packages/webc-patterns#readme).
|
|
4
4
|
|
|
5
5
|
See it in the [component preview](https://allonsy-studio.github.io/webc-resources/).
|
|
6
6
|
|
|
7
|
+
Using an AI coding agent? Point it at [`llms.txt`](llms.txt): the rules for calling & styling the components, & a reference of every prop, slot, & token.
|
|
8
|
+
|
|
7
9
|
## Status
|
|
8
10
|
|
|
9
11
|
Beta. Versions are `0.1.0-beta.N` until 1.0.
|
|
@@ -21,7 +23,7 @@ Evergreen browsers from about 2024. Features newer than that degrade gracefully.
|
|
|
21
23
|
|
|
22
24
|
## Use it
|
|
23
25
|
|
|
24
|
-
Add the OSS site plugin in place of the Norn plugin, with the same options. It adds the Norn plugin with the OSS components, fills `norn-base`'s hooks, embeds the brand tokens, sets the theme color,
|
|
26
|
+
Add the OSS site plugin in place of the Norn plugin, with the same options. It adds the Norn plugin with the OSS components, fills `norn-base`'s hooks, embeds the brand tokens, sets the theme color, & copies the fonts to `assets/fonts`:
|
|
25
27
|
|
|
26
28
|
```js
|
|
27
29
|
import path from "node:path";
|
|
@@ -43,7 +45,7 @@ export default function (config) {
|
|
|
43
45
|
}
|
|
44
46
|
```
|
|
45
47
|
|
|
46
|
-
Pages pick a layout from the patterns package: `norn-landing.webc`, `norn-docs-home.webc`
|
|
48
|
+
Pages pick a layout from the patterns package: `norn-landing.webc`, `norn-docs-home.webc` & `norn-docs.webc`, or `norn-workspaces-home.webc` & `norn-workspace.webc`. Its README lists each layout's props & shows how to [copy a layout](https://github.com/allonsy-studio/webc-resources/tree/main/packages/webc-patterns#copy-a-layout) to change it. Don't add the Norn plugin as well: the OSS site plugin adds it, & a second one fails the build. The project's own `fillHooks` calls append after the theme's.
|
|
47
49
|
|
|
48
50
|
The site data comes from the patterns package's builders, one line per data file. Pass the theme's `host` so a project without its own URL gets its path on Allons-y Studio's pages host:
|
|
49
51
|
|
|
@@ -61,11 +63,11 @@ export default () =>
|
|
|
61
63
|
});
|
|
62
64
|
```
|
|
63
65
|
|
|
64
|
-
For the npm badges in the footer, add `npmRelease`
|
|
66
|
+
For the npm badges in the footer, add `npmRelease` & `badgeColor` to the site data, from the patterns package's `npmRelease` & `accentHex`. The [landing](https://github.com/allonsy-studio/webc-resources/tree/main/fixtures/landing), [docs](https://github.com/allonsy-studio/webc-resources/tree/main/fixtures/docs), & [workspaces](https://github.com/allonsy-studio/webc-resources/tree/main/fixtures/workspaces) fixtures are complete working projects.
|
|
65
67
|
|
|
66
68
|
### ossProps
|
|
67
69
|
|
|
68
|
-
`ossProps(site, project, { docs, anchors, oss })` maps the site facts from `buildSite`
|
|
70
|
+
`ossProps(site, project, { docs, anchors, oss })` maps the site facts from `buildSite` & a `project.json` to the layout props, with the OSS site theme's link set in English: the header's section anchors (with `anchors`), Docs (with a book icon, when `docs` has pages), GitHub, & npm links; the footer's name, tagline, npm badges once the package is released, license, & the Project & Help groups. Conduct & security links come from the project's own files first, then Allons-y Studio's policies; `oss: false` leaves them out. A project adds its page's own props, such as `title`, `docs`, & `ogImage`, after it. It never throws on missing data.
|
|
69
71
|
|
|
70
72
|
## Components
|
|
71
73
|
|
|
@@ -74,13 +76,13 @@ For the npm badges in the footer, add `npmRelease` and `badgeColor` to the site
|
|
|
74
76
|
| `oss-bar` | Yes | The banner, in the `banner` hook before the header |
|
|
75
77
|
| `oss-cta` | Yes | The call to action that closes `main`, in the `cta` hook, with the Allons-y Studio name signed in Yellowtail. The only place Allons-y Studio's contact address appears |
|
|
76
78
|
| `oss-credit` | Yes | The footer credit, in the `credit` hook, light or dark by the visitor's scheme, cropped to the art |
|
|
77
|
-
| `oss-head` | No | The `head` hook: the PT Mono preload
|
|
79
|
+
| `oss-head` | No | The `head` hook: the PT Mono preload & the self-hosted `@font-face` rules, with a fallback matched to each font's metrics |
|
|
78
80
|
|
|
79
81
|
The Allons-y Studio SVGs are inlined into the three locked components when the package is packed, from the org's `.github` repository, so the package exports no asset folder for them. Each has an accessible name, or is marked decorative. A packed install needs network access once, at pack time; set `OSS_ASSETS` to a local checkout's `assets` folder to pack offline.
|
|
80
82
|
|
|
81
83
|
## The brand
|
|
82
84
|
|
|
83
|
-
The theme is two files in the `norn.oss` layer, which the plugin embeds in every page's bundle: `css/tokens.css` sets shared tokens,
|
|
85
|
+
The theme is two files in the `norn.oss` layer, which the plugin embeds in every page's bundle: `css/tokens.css` sets shared tokens, & `css/brand.css` styles the Norn components by their tags. A project's unlayered CSS still wins over each of them.
|
|
84
86
|
|
|
85
87
|
| Token | Allons-y Studio value |
|
|
86
88
|
| --- | --- |
|
|
@@ -89,40 +91,43 @@ The theme is two files in the `norn.oss` layer, which the plugin embeds in every
|
|
|
89
91
|
| Rule in `css/brand.css` | Allons-y Studio look |
|
|
90
92
|
| --- | --- |
|
|
91
93
|
| `norn-header > header::after` | The four-color strip along the header bar |
|
|
92
|
-
| `norn-footer > footer > div:first-child > :first-child strong:first-of-type` | The footer's project name in the accent color
|
|
94
|
+
| `norn-footer > footer > div:first-child > :first-child strong:first-of-type` | The footer's project name in the accent color & the mono face, at 1.2rem |
|
|
93
95
|
|
|
94
|
-
The plugin also sets the theme color, `#33394e`,
|
|
96
|
+
The plugin also sets the theme color, `#33394e`, & `og:locale`, `en_US`, as prop defaults under the project's mapping.
|
|
95
97
|
|
|
96
98
|
## Exports
|
|
97
99
|
|
|
98
100
|
| Export | Purpose |
|
|
99
101
|
| --- | --- |
|
|
100
102
|
| `default` | The OSS site plugin, `config.addPlugin(oss, options)`, with the Norn plugin's options |
|
|
101
|
-
| `ossProps(site, project, options)` | Layout props from the site facts
|
|
103
|
+
| `ossProps(site, project, options)` | Layout props from the site facts & `project.json`, with the OSS site theme's link set |
|
|
102
104
|
| `ossEnabled({ packagePath })` | False when the project's `package.json` sets `"oss-docs": { "oss": false }` |
|
|
103
105
|
| `host` | Allons-y Studio's pages host, for `buildSite` |
|
|
104
|
-
| `policies` | Allons-y Studio's conduct
|
|
106
|
+
| `policies` | Allons-y Studio's conduct & security policy URLs |
|
|
105
107
|
| `components` | Absolute glob for the OSS components, which the plugin adds |
|
|
106
108
|
| `tokens` | Absolute path to `css/tokens.css` |
|
|
107
109
|
| `brand` | Absolute path to `css/brand.css` |
|
|
108
110
|
| `fonts` | Absolute path to the self-hosted font files, which the plugin copies to `assets/fonts` |
|
|
109
111
|
|
|
110
|
-
The schema for the `oss-docs` settings is exported as `@allons-y/webc-oss-site/schema/oss-docs.schema.json`, the brand tokens as `@allons-y/webc-oss-site/css/tokens.css`,
|
|
112
|
+
The schema for the `oss-docs` settings is exported as `@allons-y/webc-oss-site/schema/oss-docs.schema.json`, the brand tokens as `@allons-y/webc-oss-site/css/tokens.css`, & the brand rules as `@allons-y/webc-oss-site/css/brand.css`.
|
|
111
113
|
|
|
112
114
|
## The OSS lock
|
|
113
115
|
|
|
114
|
-
A project component named `oss-bar.webc`, `oss-cta.webc`, or `oss-credit.webc` collides with the packaged one
|
|
116
|
+
A project component named `oss-bar.webc`, `oss-cta.webc`, or `oss-credit.webc` collides with the packaged one & fails the build, & no page data can remove the hook fills. Opting out is a setting: with `"oss-docs": { "oss": false }` in the project's `package.json`, the project's config adds the Norn plugin in place of the OSS site plugin (`ossEnabled` reads the setting), & passes `oss: false` to `ossProps`. No banner, call to action, credit, OSS CSS, or Allons-y Studio link is left on the page.
|
|
115
117
|
|
|
116
118
|
## Notes
|
|
117
119
|
|
|
118
|
-
- **Icons come from `norn-icon`.** The Docs link carries a book, the hero facts a check,
|
|
119
|
-
- **Conduct
|
|
120
|
+
- **Icons come from `norn-icon`.** The Docs link carries a book, the hero facts a check, & a docs page may name a sidebar icon. Footer links & card badges have none, & `features[].icon` is not in the schema.
|
|
121
|
+
- **Conduct & security links** use the project's own `CODE_OF_CONDUCT.md` & `SECURITY.md` when it keeps them, & show Allons-y Studio's only when the OSS site layer is on.
|
|
120
122
|
- **The workspaces sidebar** is labeled "Packages", not "Documentation".
|
|
121
|
-
- **The OSS credit
|
|
123
|
+
- **The OSS credit & call to action** are inline SVGs, not image files.
|
|
122
124
|
|
|
123
125
|
## License
|
|
124
126
|
|
|
125
|
-
[MPL-2.0](LICENSE): use freely, modify as needed; changes to MPL-licensed files
|
|
127
|
+
> [MPL-2.0](LICENSE): use freely, modify as needed; changes to MPL-licensed files
|
|
128
|
+
> should be shared back under the same license.
|
|
129
|
+
|
|
130
|
+
---
|
|
126
131
|
|
|
127
132
|
<p align="center">
|
|
128
133
|
<a href="https://allons-y.studio">
|
package/llms.txt
ADDED
|
@@ -0,0 +1,70 @@
|
|
|
1
|
+
# @allons-y/webc-oss-site
|
|
2
|
+
|
|
3
|
+
> The Allons-y Studio theme for Norn sites: brand tokens and rules, self-hosted fonts, and the locked `oss-bar`, `oss-cta`, `oss-credit`, and `oss-head` components. Use it only for Allons-y Studio open source sites. Everything generic lives in `@allons-y/webc-patterns`; read its `llms.txt` first. The reference at the end is generated from the component sources.
|
|
4
|
+
|
|
5
|
+
## What you are working with
|
|
6
|
+
|
|
7
|
+
- A plugin, `@allons-y/webc-oss-site`, that you add in place of the Norn plugin with the same options. It adds the Norn plugin, fills the four hooks (`head`, `banner`, `cta`, `credit`), embeds the brand tokens and rules, sets the theme color and locale, and copies the fonts to `assets/fonts`.
|
|
8
|
+
- `ossProps(site, project, { docs, anchors, oss })`: maps the site facts and `project.json` to layout props with the theme's English link set (header links, Docs, GitHub, npm, footer groups, conduct and security policies).
|
|
9
|
+
- The components are hook fills. A page does not call them.
|
|
10
|
+
|
|
11
|
+
## Rules
|
|
12
|
+
|
|
13
|
+
- **Never add the Norn plugin as well.** The OSS plugin adds it, and a second registration fails the build.
|
|
14
|
+
- **`oss-bar`, `oss-cta`, `oss-credit` are locked.** A project file with one of those names fails the build. A project opts out of the whole studio layer with `"oss-docs": { "oss": false }` in `package.json`. Do not edit, copy, or hide them with CSS.
|
|
15
|
+
- The brand lives in the `norn.oss` layer: `css/tokens.css` sets the mono font token and `css/brand.css` styles the header strip and footer name with rules on the component tags. To change the look, override global tokens in the project's own stylesheet. Components have no theme hooks.
|
|
16
|
+
- Project-specific head markup goes through `fillHooks(config, { head: "…" })` from `@allons-y/webc-patterns/plugin`. The project's fills append after the theme's.
|
|
17
|
+
- Item data uses `href`, `title`, `description` like every Norn layout. `ossProps` returns it that way, and the `docs` you pass in must too.
|
|
18
|
+
- Site data comes from the patterns package's builders (`buildSite`, with `host` from this package). The `fixtures/landing`, `fixtures/docs`, and `fixtures/workspaces` folders are complete working projects.
|
|
19
|
+
- The package needs network access once at pack time to inline the org's SVGs. Set `OSS_ASSETS` to a local `assets` folder to pack offline.
|
|
20
|
+
|
|
21
|
+
## Where to look next
|
|
22
|
+
|
|
23
|
+
- README: the full plugin example, `ossProps`, the components table.
|
|
24
|
+
- Component preview: https://allonsy-studio.github.io/webc-resources/
|
|
25
|
+
|
|
26
|
+
## Reference
|
|
27
|
+
|
|
28
|
+
Generated from the component sources and their CSF files. Do not edit by hand: run `yarn llms`.
|
|
29
|
+
|
|
30
|
+
### Container components
|
|
31
|
+
|
|
32
|
+
A bounded surface that holds content: a card, a card grid, a section, a hero.
|
|
33
|
+
|
|
34
|
+
#### oss-cta
|
|
35
|
+
|
|
36
|
+
Tag: `<oss-cta>`.
|
|
37
|
+
|
|
38
|
+
OSS call to action, at the foot of the page. Locked: its copy and actions are fixed, and it takes no slots. The one setting is the heading level. Closes the page body, above the footer: the `cta` hook places it last. The Allons-y Studio name is signed in the signature face, Yellowtail, which `oss-head` declares. Its actions are `norn-link-button`s, colored by setting the global accent tokens on `oss-cta`. The one place Allons-y Studio's contact address appears. The mark is inlined from the org's assets by `scripts/inline-svg.js`.
|
|
39
|
+
|
|
40
|
+
Props:
|
|
41
|
+
|
|
42
|
+
- `level` (number, optional, default `2`, one of `2`, `3`, `4`): The heading level, to fit the page outline. Any other value gives the default.
|
|
43
|
+
|
|
44
|
+
Global tokens it reads: `--norn-ui-border-radius`, `--norn-space-s`, `--norn-space-m`, `--norn-space-l`, `--norn-space-xl`.
|
|
45
|
+
|
|
46
|
+
### Component components
|
|
47
|
+
|
|
48
|
+
A self-contained element: a link, a code block, a lockup.
|
|
49
|
+
|
|
50
|
+
#### oss-bar
|
|
51
|
+
|
|
52
|
+
Tag: `<oss-bar>`.
|
|
53
|
+
|
|
54
|
+
OSS banner, shown before the page's header. Locked: it takes no props or slots. The SVG is inlined from the org's assets by `scripts/inline-svg.js`, cropped to the lockup. It shows at full size from 31.25rem up and scales down below that, so the text stays readable on a phone and grows with the text size.
|
|
55
|
+
|
|
56
|
+
#### oss-credit
|
|
57
|
+
|
|
58
|
+
Tag: `<oss-credit>`.
|
|
59
|
+
|
|
60
|
+
OSS credit lockup for the footer, light or dark by the scheme the page uses. Locked: it takes no props or slots. One SVG, inlined from the org's light and dark assets by `scripts/inline-svg.js` and cropped to the art. The two assets differ only in paint, so the script merges them: each changed `fill` and `stroke` reads `light-dark(light, dark)`, which follows the page's `color-scheme`, set by the visitor's preference or by CSS.
|
|
61
|
+
|
|
62
|
+
### Document components
|
|
63
|
+
|
|
64
|
+
The head and the foundation styles, with no body markup.
|
|
65
|
+
|
|
66
|
+
#### oss-head
|
|
67
|
+
|
|
68
|
+
Tag: `<oss-head>`.
|
|
69
|
+
|
|
70
|
+
The OSS site head: the PT Mono preload and the self-hosted `@font-face` rules for PT Mono, Instrument Sans, and Yellowtail, each with a fallback matched to its metrics. The OSS site plugin puts it in `norn-base`'s head hook, followed by the brand tokens from `css/tokens.css`. Call it elsewhere as `<meta webc:is="oss-head" webc:nokeep />`. The `@font-face` rules look for the fonts at `assets/fonts`, one level up from the bundle: the OSS site plugin copies the package's `fonts` folder there. The brand tokens it goes with, in `css/tokens.css` and the `norn.oss` layer, are below. The brand rules in `css/brand.css` follow them in the same layer, such as the four-color strip along the header bar and the footer's project name in the accent color and the mono face, at 1.2rem. A project's unlayered CSS still wins over both.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@allons-y/webc-oss-site",
|
|
3
|
-
"version": "0.1.0-beta.
|
|
3
|
+
"version": "0.1.0-beta.3",
|
|
4
4
|
"description": "The OSS site theme for Norn sites: Allons-y Studio brand tokens, self-hosted fonts, and the locked OSS banner, call to action, and footer credit.",
|
|
5
5
|
"license": "MPL-2.0",
|
|
6
6
|
"author": "Cassondra Roberts <castastrophe@users.noreply.github.com> (https://allons-y.studio)",
|
|
@@ -32,7 +32,8 @@
|
|
|
32
32
|
"schema/",
|
|
33
33
|
"index.js",
|
|
34
34
|
"LICENSE",
|
|
35
|
-
"README.md"
|
|
35
|
+
"README.md",
|
|
36
|
+
"llms.txt"
|
|
36
37
|
],
|
|
37
38
|
"scripts": {
|
|
38
39
|
"prepack": "node ../../scripts/build-components.js webc-oss-site && yarn copy:svg && yarn copy:fonts",
|