SolidOS · timea-solid · Apr 19, 2026 · Apr 19, 2026 · Apr 19, 2026 · Apr 19, 2026
diff --git a/.gitignore b/.gitignore
@@ -0,0 +1,3 @@
+node_modules/
+packages/*/dist/
+examples/*/dist/
diff --git a/README.md b/README.md
@@ -1,2 +1,78 @@
 # solid-assets
-Solid theme and icons
+
+npm-publishable monorepo for SolidOS theme tokens and icons.
+
+## Packages
+
+- `@solidos/tokens`: frameworkless theme CSS variables with light/dark mode.
+- `@solidos/icons`: SVG UI icons and multi-color logos.
+
+## Workspace setup
+
+```bash
+npm install
+```
+
+## Build
+
+```bash
+npm run build
+```
+
+This runs all workspace build scripts and produces publishable package outputs in each package `dist/` directory.
+
+## Webpack demo
+
+A fully working webpack 5 example lives in [`examples/webpack-demo/`](./examples/webpack-demo/README.md).
+It demonstrates importing theme tokens and tree-shaken icons in a real application bundle.
+
+## Webpack consumer example
+
+Use webpack 5 asset modules so only imported icons are emitted:
+
+```js
+// webpack.config.js
+module.exports = {
+  module: {
+    rules: [
+      {
+        test: /\.svg$/i,
+        type: 'asset/resource'
+      }
+    ]
+  }
+};
+```
+
+Import tokens and one icon file:
+
+```ts
+import '@solidos/tokens/themes.css';
+import searchIconUrl from '@solidos/icons/icons/search.svg';
+
+document.documentElement.dataset.theme = 'light';
+
+const icon = document.createElement('span');
+icon.className = 'Icon';
+icon.style.setProperty('--icon-mask', `url("${searchIconUrl}")`);
+```
+
+```css
+.Icon {
+  width: 20px;
+  height: 20px;
+  background: var(--icon-color);
+  -webkit-mask: var(--icon-mask) no-repeat center / contain;
+  mask: var(--icon-mask) no-repeat center / contain;
+}
+```
+
+Use logos through `<img>`:
+
+```ts
+import logoUrl from '@solidos/icons/logos/solidos.svg';
+
+const logo = document.createElement('img');
+logo.src = logoUrl;
+logo.alt = 'SolidOS';
+```
diff --git a/examples/webpack-demo/README.md b/examples/webpack-demo/README.md
@@ -0,0 +1,43 @@
+# webpack-demo
+
+A minimal webpack 5 project that demonstrates consuming `@solidos/tokens` and `@solidos/icons` in an application bundle.
+
+## What it shows
+
+- **SVGs as asset modules** – webpack emits only the SVG files you import via `type: 'asset/resource'`, keeping the bundle small.
+- **CSS theme tokens** – `@solidos/tokens/themes.css` is extracted into a standalone stylesheet by `mini-css-extract-plugin`.
+- **Light / dark theming** – toggled at runtime by setting `data-theme` on `<html>`.
+- **Icon rendering** – single-color UI icons via CSS `mask-image` + `--icon-color`; multi-color logo via `<img>`.
+
+## Prerequisites
+
+Build the workspace packages first so the `dist/` outputs exist:
+
+```bash
+# from the repo root
+npm install
+npm run build
+```
+
+## Run the demo
+
+```bash
+cd examples/webpack-demo
+npm install
+npm run build   # production bundle → dist/
+npm run dev     # webpack dev-server with HMR
+```
+
+## Key webpack configuration
+
+```js
+// webpack.config.js (excerpt)
+{
+  test: /\.svg$/i,
+  type: 'asset/resource'   // tree-shakeable: only imported SVGs are emitted
+},
+{
+  test: /\.css$/i,
+  use: [MiniCssExtractPlugin.loader, 'css-loader']
+}
+```