Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 8 additions & 8 deletions docs/docs/design/brand-assets.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,8 +3,7 @@
Status: **In use** — `ComlineProject/brand` holds the canonical files; the docs
site vendors the mark and favicon from it. Other consumers still carry their own
copies · Affects `ComlineProject/brand`, `ComlineProject/docs`,
`ComlineProject/package-registry-frontend`, `ComlineProject/shared-web`,
`ComlineProject/comline`
`ComlineProject/package-registry-frontend`, `ComlineProject/comline`

## The problem

Expand Down Expand Up @@ -74,7 +73,6 @@ instead.
|---|---|---|
| `docs` | `docs/docs/assets/` | `mkdocs.yml` `theme.logo` / `theme.favicon` |
| `package-registry-frontend` | `static/images/comline/`, `static/favicon.*` | header bar, `app.html` |
| `shared-web` | per its own convention | shared web components |
| `comline` (landing) | `static/` | header, hero |

## Follow-ups
Expand All @@ -83,12 +81,14 @@ instead.
`palette.primary` to a custom tomato (`--md-primary-fg-color: #E5442E`) would
put the header on-brand; it needs a contrast check against the header text and
the two colour schemes before it lands.
- **`shared-web` as the web consumers' relay.** If the playground, tutorial, and
landing site end up sharing a component layer (`shared-web`), that layer — not
each app — should carry the one vendored copy.
- **`comline-web-kit` as the web consumers' relay.** The playground and the
tutorial share `comline-web-kit` (a workspace of `ComlineProject/playground`),
whose views take their colours from `--cl-*` custom properties. Brand colours
that more than one site needs belong in the kit's defaults, not in each app.
`shared-web`, the earlier attempt at a shared layer, was never used.
- **`tokens.json` → build input.** Nothing consumes `tokens.json` yet. A web
build could generate a CSS custom-property file from it so the colours are
never retyped.
- **Other consumers.** `package-registry-frontend`, `shared-web`, and the
landing site still carry their originals; each should re-copy from `brand` and
- **Other consumers.** `package-registry-frontend` and the landing site still
carry their originals; each should re-copy from `brand` and
add a provenance note the way the docs site now does.
35 changes: 21 additions & 14 deletions docs/docs/design/playground-and-tutorial.md
Original file line number Diff line number Diff line change
Expand Up @@ -198,22 +198,29 @@ work on the analysis layer benefits both.
validators → imports → generate → runtime. The `tutorial` README wants each
step to *simulate* running machines with distinct local/remote panels and live
stats — the loopback runtime above is the engine for that.
- **Not sharing yet, in practice.** The one lesson built so far ("two services
talk") is a standalone widget (`ComlineProject/tutorial`'s
`Simulation.svelte`) driving `comline-simulator` directly — it reuses neither
the playground's `comline-playground-wasm` (the editor) nor its `sim/ui/*.ts`
components. The "same WASM module and component library" plan below hasn't
materialised for the runtime piece; revisit once more lessons exist.
- **Shared through `comline-web-kit`.** The playground's editor and simulate
view are a package, `comline-web-kit`: a workspace of
`ComlineProject/playground` that other sites install by git, the way they
install `comline-simulator`
([playground#118](https://github.com/ComlineProject/playground/issues/118)).
- `comline-web-kit/sim` is the simulate view. Its **lesson layout** shows a
fixed scene from a session link: no palette, nothing to add, move or
remove, only a server's behaviours and a client's calls, stacked in one
column and fitted to the page. The tutorial's "Try it" lesson runs on it.
- `comline-web-kit/editor` is the CodeMirror editor and the compile
worker. No lesson uses it yet; a lesson with a live editor will.
- `comline-web-kit/sim.css` is scoped under `.cl-sim` and themed with
`--cl-*` properties, so the tutorial keeps its own palette.

## Where it lives / embedding

**Reality diverged from the "SvelteKit for both" plan below.** The playground
ended up Vite + vanilla TS + CodeMirror (see the status line above); only the
tutorial is SvelteKit. There's no neutral TS package or shared Svelte component
library — the tutorial's one interactive lesson so far is a standalone widget
against `comline-simulator` directly (see
[Playground vs tutorial](#playground-vs-tutorial)). The plan as originally
written:
tutorial is SvelteKit. What's shared is the plan's first half: a
framework-neutral TS package, `comline-web-kit`, that both apps mount (see
[Playground vs tutorial](#playground-vs-tutorial)). The second half, a Svelte
component library, isn't needed: a Svelte page mounts the kit's views through an
action. The plan as originally written:

**SvelteKit for the apps, framework-neutral for what's shared.** The
`playground` and `tutorial` stay SvelteKit (the existing scaffold). Below them:
Expand Down Expand Up @@ -242,9 +249,9 @@ subdomains.
- **Target** — everything: compile + diagnostics + codegen + a runtime demo. No
cut-down first release; the runtime demo simply fills in per language.
- **Framework** — *superseded in practice*: the playground shipped Vite +
vanilla TS + CodeMirror, not SvelteKit; only the tutorial is SvelteKit, and
its one interactive lesson is a standalone widget, not a shared component
library. See [Where it lives / embedding](#where-it-lives-embedding).
vanilla TS + CodeMirror, not SvelteKit; only the tutorial is SvelteKit. They
share framework-neutral TS, `comline-web-kit`, not a component library. See
[Where it lives / embedding](#where-it-lives-embedding).

## Findings so far

Expand Down
Loading