bref-ui-themes 0.1.0 → 1.0.0

package/README.md

@@ -1,111 +1,134 @@
 # bref-ui-themes
 
-Reusable Svelte 5 themes for [bref-ui](https://github.com/feuersteiner/bref-ui), with interactive demos and native CSS. Version 0.1.0 is an unpublished review candidate built on SvelteKit 3 and published Bref 2.2.0.
+Reusable themes for [Bref-ui](../readme.md), each intended to have its own public
+entry point. Theme implementations are reviewed in separate pull requests.
 
-[Explore the showcase](https://feuersteiner.github.io/bref-ui-themes/) · [Bref documentation](https://feuersteiner.github.io/bref-ui/) · [Join Discord](https://discord.gg/JpgQRTUsVS)
+The Todo, House Shop and RunnerAI demos use canonical Bref components and palette
+configuration. Their sources and previews live in [docs](../docs/README.md).
 
-## Local development
+https://github.com/user-attachments/assets/3326a5c3-0573-4b40-bb8e-9a10da1fd6ac
 
-Requires Bun 1.3.4 or newer. The scaffold uses Svelte 5, SvelteKit 3, Vite 8 and `svelte-package` 3.
+See New Paris, VS Code and Glassy in action. The [video app and storyboard](../video-demo/README.md)
+are part of this repository.
+
+## Installation
+
+Install [bref-ui-themes from npm](https://www.npmjs.com/package/bref-ui-themes) in a Svelte 5 app:
 
 ```sh
-bun install
-bun run dev                     # http://localhost:5173
-bun run check
-bun run lint
-bun run package                 # library → dist; includes publint
-bun run build:site              # static showcase → build
-bun run build                   # site + library
-bun run preview                 # preview the production site
-bun pm pack                     # creates a local npm tarball; does not publish
+npm install bref-ui bref-ui-themes
 ```
 
-The restored GitHub Pages workflow builds `build:site` on pushes to `main`, using the Pages base path and uploading `build`. To reproduce the project-path build locally:
+Bref-ui 3 and Svelte 5 are peer dependencies. The custom text font remains optional.
 
-```sh
-BASE_PATH=/bref-ui-themes bun run build:site
-BASE_PATH=/bref-ui-themes bun run preview # http://localhost:4173/bref-ui-themes/
+Import components from the theme's entry point:
+
+```svelte
+<script>
+	import { Theme, Button } from 'bref-ui-themes/new-paris';
+</script>
+
+<Theme><Button label="Save" /></Theme>
 ```
 
-## Showcase and demo sites
+## Development
 
-Open the [showcase](http://localhost:5173/). The showcase uses base `bref-ui` Theme, Button, Surface, Pill and Icon components, default palette/styles, documentation fonts and the Bref logo. Each card uses an actual browser screenshot and links to the working site. Every demo provides a Showcase link; navigation between themes reloads the document to avoid retaining global CSS.
+Run `bun install` and `bun run dev` from the repository root. The docs site consumes
+public workspace source exports directly. Package-level `check`, `build` and `prepack`
+remain available here; `src/lib` holds published sources and `src/routes` is only
+a local library preview.
 
-| Demo          | Implemented interactions                                                                  | Site                                          | Theme demonstration                                         |
-| ------------- | ----------------------------------------------------------------------------------------- | --------------------------------------------- | ----------------------------------------------------------- |
-| Tasks         | Project creation/filtering, task status tabs, search, completion and task editing         | [/relay](http://localhost:5173/relay)         | [/themes/relay](http://localhost:5173/themes/relay)         |
-| House Shop    | Category tabs, furniture sorting, product dialogs, cart quantities and simulated checkout | [/forma](http://localhost:5173/forma)         | [/themes/forma](http://localhost:5173/themes/forma)         |
-| Site Reviewer | URL validation, simulated audit progress, history and finding review tabs                 | [/elsewhere](http://localhost:5173/elsewhere) | [/themes/elsewhere](http://localhost:5173/themes/elsewhere) |
+Packing includes this README and a generated copy of the repository MIT license.
+Edit the root license; generated package copies are ignored.
 
-![Tasks rendered demo](static/previews/relay.jpg)
-![House Shop rendered demo](static/previews/forma.jpg)
-![Site Reviewer rendered demo](static/previews/elsewhere.jpg)
+Shared types come directly from `bref-ui/types` and are re-exported as types from
+`bref-ui-themes`. The root entry does not aggregate components or load theme CSS.
+New Paris depends on Material Symbols and loads its variable fill font through Theme.
 
-**WIP:** VS Code, Liquid Glass and Minimalist Blocky are planned. They have no exports, demonstration routes or availability links.
+## New Paris
 
-## Library imports
+Black and ivory controls, serif typography and opaque paper overlays. All twenty components are exported through the theme subpath.
 
-Install the local tarball with `bun add ./bref-ui-themes-0.1.0.tgz`. Consumers need Svelte `^5.57.1` and Bref `^2.2.0` (peer dependencies). Fonts used by the themes are package dependencies.
+Material Symbols icons load automatically with Theme. The custom text font, Inter,
+is optional to avoid adding unused font assets to apps; text falls back to system
+fonts. To match the gallery typography, install and import Inter:
+
+```sh
+npm install @fontsource-variable/inter
+```
 
 ```svelte
-<script lang="ts">
-	import { Theme, Button } from 'bref-ui-themes/relay';
+<script>
+	import '@fontsource-variable/inter/index.css';
+	import { Theme, Button } from 'bref-ui-themes/new-paris';
 </script>
 
-<Theme>
-	<Button label="Create project" variant="filled" color="primary" />
-</Theme>
+<Theme><Button label="Save" /></Theme>
 ```
 
-The same API is available from each implemented theme:
+The gallery uses the same public package exports at `/themes/new-paris`.
+
+## Glassy
+
+Translucent controls and frosted overlays with scoped component styling. All twenty components are exported through the theme subpath:
+
+```svelte
+<script>
+	import { Theme, Button } from 'bref-ui-themes/glassy';
+</script>
 
-```ts
-import { Theme, Button } from 'bref-ui-themes/forma';
-// Or: import { Theme, Button } from 'bref-ui-themes/elsewhere';
-// Namespace exports: import { Relay, Forma, Elsewhere } from 'bref-ui-themes';
+<Theme><Button label="Save" /></Theme>
 ```
 
-Each entry exports `Theme`, `Button`, `Checkbox`, `Dialog`, `Icon`, `Pill`, `PillChoiceGroup`, `PillGroup`, `Popover`, `Progress`, `Select`, `Spinner`, `Surface`, `Tabs` and `TextInput`. `Theme` takes an optional `children` snippet. Controls retain Bref's props, native attributes and applicable bindings; their types remain imported from `bref-ui/types`.
+Material Symbols icons load automatically with Theme. Inter remains optional; to
+match the gallery typography, install `@fontsource-variable/inter` and import
+`@fontsource-variable/inter/index.css` in the app.
 
-### Tabs
+The gallery uses the same public package exports at `/themes/glassy`.
 
-`Tabs` uses Bref 2.2.0's readonly item data, required icon names and bindable string value. The consumer renders the selected content:
+## Crystal Code
+
+Light and dark frosted workbench controls with a complete component reference. All twenty components are exported through the theme subpath:
+
+```svelte
+<script>
+	import { Theme, Button } from 'bref-ui-themes/crystal-code';
+</script>
+
+<Theme><Button label="Save" /></Theme>
+```
+
+Material Symbols icons load automatically with Theme. Inter remains optional; to
+match the gallery typography, install and import it:
+
+```sh
+npm install @fontsource-variable/inter
+```
 
 ```svelte
-<script lang="ts">
-	import { Theme, Tabs } from 'bref-ui-themes/relay';
-	import type { TabItemDataProps } from 'bref-ui/types';
-	let view = $state('overview');
-	const items = [
-		{ id: 'overview', label: 'Overview', icon: 'dashboard' },
-		{ id: 'activity', label: 'Activity', icon: 'history' },
-		{ id: 'reports', label: 'Reports', icon: 'monitoring', disabled: true }
-	] as const satisfies readonly TabItemDataProps[];
+<script>
+	import '@fontsource-variable/inter/index.css';
+	import { Theme, Button } from 'bref-ui-themes/crystal-code';
 </script>
 
-<Theme>
-	<Tabs {items} bind:value={view} label="Project views" />
-	<div role="tabpanel" aria-label={items.find((item) => item.id === view)?.label} tabindex="0">
-		{#if view === 'overview'}<p>8 tasks open, 3 completed.</p>
-		{:else}<p>The navigation review was completed today.</p>{/if}
-	</div>
-</Theme>
+<Theme><Button label="Save" icon={{ name: 'check' }} /></Theme>
 ```
 
-Horizontal tabs accept `size="fit"` (default, scrolls on overflow) or `size="fill"`. Vertical tabs use `orientation="vertical"` without `size`. Optional `onChange`, `filled`, `transitionIn` and `transitionOut` retain the published API. Default indicator motion respects reduced motion; custom transitions should do the same. Arrow keys, Home and End move selection and skip disabled items. At small widths, horizontal tabs show the selected label, and vertical tabs show icons; accessible names remain available. Each theme demonstration includes fit, fill, vertical, disabled and bound-content examples.
+The gallery uses the same public package exports at `/themes/crystal-code`.
 
-These initial themes provide the demo palettes, fonts, common CSS and component styling. They use light mode and document-global Bref tokens/reset styles; mount one theme per document and use full-page navigation when changing themes. Site-specific layouts and content are separate from the library.
+## VS Code
 
-## Source layout
+Fixed-dark workbench controls with native interactions and scoped styling. All twenty components are exported through the theme subpath:
 
-- `src/lib/<theme>/index.ts`: public theme entry; each site's demo and theme demonstration consume it.
-- `src/lib/components`: Bref CLI-copied controls and their local dependencies, with `bref-ui/types` imports preserved.
-- `src/lib/shared`: common reusable theme styling.
-- `src/routes/(sites)`: complete Tasks, House Shop and Site Reviewer sites and the latest shared demo shell.
-- `src/routes/(themes)`: demonstrations of implemented public theme exports.
-- `src/routes/catalog`: showcase content adapted from the reusable gallery.
-- `static/demos`: original photographic assets; `static/previews`: rendered catalog previews. Neither is included in the npm package.
+```svelte
+<script>
+	import { Theme, Button } from 'bref-ui-themes/vscode';
+</script>
+
+<Theme><Button label="Save" icon={{ name: 'check' }} /></Theme>
+```
 
-The migration preserves the local checkbox motion/reduced-motion fix and animated dialog title/icon updates. Only demo-owned files were extracted from their source branches; the latest Relay shared shell was kept. See [verification.md](verification.md) for source revisions, validation and remaining limitations.
+Material Symbols icons load automatically with Theme. Text uses system fonts, so
+no custom text font installation is required.
 
-Tabs was copied from the npm-installed Bref 2.2.0 source using its registry, dependency planner and preview/install pipeline. Existing Icon and Theme dependencies were retained. The preview added only `tabs/tabs.svelte` and `tabs/item.svelte`, with explicit approval for the shared barrel merge; no existing component source was overwritten. Tabs types remain public imports from `bref-ui/types`.
+The gallery uses the same public package exports at `/themes/vscode`.