chore: 🤖 consolidate development environment (technical debt)

.storybook/Introduction.mdx

@@ -0,0 +1,17 @@
+<div style={{ marginBottom: '20px' }}>
+  <img src='/clickhouse-backs.png' alt='Click UI' style={{width: '100%', borderRadius: '4px'}} />
+</div>
+
+# Click UI
+
+Click UI is the ClickHouse design system and component library. Our aim with Click UI is to provide an accessible, theme-able, modern, and attractive interface with which to experience the speed and power of ClickHouse.
+
+This site is a reference for inspecting components and their props. Official documentation lives at [clickhouse.design/click-ui](https://clickhouse.design/click-ui).
+
+## Resources
+
+* **Source Code:** Available on [GitHub](https://github.com/ClickHouse/click-ui)
+* **Package:** Found on [NPM](https://www.npmjs.com/package/@clickhouse/click-ui)
+* **Figma:** We will be publishing Click UI to the Figma community soon.
+
+To get started, please refer to the [Quick Start Guide](https://github.com/ClickHouse/click-ui?tab=readme-ov-file#quick-start).

.storybook/main.ts

@@ -4,9 +4,8 @@ const config: StorybookConfig = {
     disableTelemetry: true
   },
   stories: [
-    "../src/Introduction.mdx",
-    "../src/components/icons/Icons.mdx",
-    "../src/**/*.stories.@(js|jsx|ts|tsx)",
+    "./Introduction.mdx",
+    "../src/**/*.stories.@(ts|tsx)",
   ],
 
   addons: ["@storybook/addon-links", //"@storybook/addon-interactions",

README.md

@@ -18,9 +18,10 @@ You can find the official docs for the Click UI design system and component libr
 ## Overview
 
 * [Requirements](#requirements)
+* [Quick Start](#quick-start)
 * [Development](#development)
   - [Generating design tokens](#generating-design-tokens)
-  - [Local development server](#local-development-server)
+  - [Local development](#local-development)
 * [Tests](#Tests)
   - [Functional tests](#functional-tests)
   - [Visual regression tests](#visual-regression-tests)
@@ -34,6 +35,31 @@ You can find the official docs for the Click UI design system and component libr
 - Nodejs (>= 22.12.x) as runtime
 - Yarn (>= 4.5.3) for development, any other package manager in a host project
 
+## Quick Start
+
+Install the package via npm or your favourite package manager:
+
+```sh
+npm i @clickhouse/click-ui@latest
+```
+
+To use Click UI, you must wrap your application in the provider. This ensures styles and themes are applied correctly across all components.
+
+```ts
+import { ClickUIProvider, Title, Text } from '@clickhouse/click-ui'
+
+function App() {
+  return (
+    <ClickUIProvider theme="dark">
+      <Title type="h1">Hello ClickHouse</Title>
+      <Text>Start building today!</Text>
+    </ClickUIProvider>
+  )
+}
+```
+
+For more examples, including theme switching and configuration, see the [How to](#how-to-use) use section, or explore our design system at [clickhouse.design/click-ui](https://clickhouse.design/click-ui).
+
 ## Development
 
 The project uses yarn package manager for development.
@@ -58,15 +84,27 @@ yarn generate-tokens
 
 Learn more about tokens-studio [here](https://documentation.tokens.studio/).
 
-### Local development server
+### Local development
+
+We leverage Storybook as our primary development environment and documentation, see [Storybook](#storybook).
 
-To run the Click UI development execute the command:
+You can start the Storybook development server by:
 
 ```sh
 yarn dev
 ```
 
-It'll default to the location [http://localhost:5173](http://localhost:5173), if port available.
+We do NOT maintain a separate development environment; our Storybook stories serve as the source of truth for component implementation.
+
+> [!IMPORTANT]
+> We operate collaboratively with the Product Design team. While stories reflect the current implementation (live), Figma files remain the source of truth for design research and decision-making. Changes are typically finalized in Figma before being implemented in code to ensure design-sync.
+
+By avoiding local preview files, we ensure that component experimentation happens in isolation; free from application side effects and providing a live look at component interfaces and usage examples at time of writing.
+
+> [!NOTE]
+> To ensure stability, we utilize Visual Regression and Unit Testing, see [tests](#tests). When contributing features or tweaks, you're expected to include or update the relevant tests to maintain stability, e.g. remember the components are consumed by a number of applications.
+
+To get started with the development playground, refer to the Storybook section [here](#storybook).
 
 ## Tests
 
@@ -145,7 +183,7 @@ The latest static version's built and deployed automatically when contributing t
 
 Once deployed it's available publicly at [clickhouse.design/click-ui](https://clickhouse.design/click-ui).
 
-## Using Click UI in an external app
+## How-to use
 
 Click UI has been tested in NextJS, Gatsby, and Vite. If you run into problems using it in your app, please create an issue and our team will try to answer.
 

package.json

@@ -41,7 +41,7 @@
     "changeset:status": "yarn changeset status",
     "changeset:version": "yarn changeset version",
     "changeset:verify": ".scripts/changeset-verification",
-    "dev": "vite",
+    "dev": "yarn storybook",
     "generate-tokens": "node build-tokens.js && prettier --write \"src/theme/tokens/*.ts\" --config .prettierrc",
     "lint": "eslint src --report-unused-disable-directives --max-warnings 0",
     "lint:fix": "eslint src --report-unused-disable-directives --max-warnings 0 --fix",