@geckoui/geckoui 2.0.0-beta-0 → 2.0.1

package/README.md

@@ -8,7 +8,9 @@
   The only thing our Gecko 🦎 eats is bugs! 🐛<br />
 </p>
 
-📚 **Documentation**: [Gecko](https://gecko.productionbug.com)
+📚 **Documentation**: [Gecko](https://geckoui.dev)
+
+Upgrading from v1? See the [migration guide](https://geckoui.dev/docs/migrating-to-v2).
 
 ## Installation
 
@@ -52,7 +54,28 @@ import "@geckoui/geckoui/styles.css";
 }
 ```
 
-### 2. Use Components
+### 2. Wrap Your App
+
+`GeckoUIProvider` owns the overlay stack. `Toast`, `ConfirmDialog` and the imperative
+`Dialog.show()` / `Drawer.show()` need it; the declarative `<Dialog open>` and
+`<Drawer open>` forms do not. Put it below your own context providers, so content opened
+from anywhere can still read them.
+
+```tsx
+import { GeckoUIProvider } from "@geckoui/geckoui";
+
+export default function RootLayout({ children }) {
+  return (
+    <html lang="en">
+      <body>
+        <GeckoUIProvider>{children}</GeckoUIProvider>
+      </body>
+    </html>
+  );
+}
+```
+
+### 3. Use Components
 
 ```tsx
 import { Alert, Button, Input } from "@geckoui/geckoui";
@@ -60,13 +83,13 @@ import { Alert, Button, Input } from "@geckoui/geckoui";
 function App() {
   return (
     <div>
-      <Button variant="contained" color="primary">
+      <Button variant="filled" color="primary">
         Click me
       </Button>
 
       <Input placeholder="Enter your name" />
 
-      <Alert variant="success" title="Operation completed successfully!" />
+      <Alert color="success" title="Operation completed successfully!" />
     </div>
   );
 }
@@ -74,64 +97,50 @@ function App() {
 
 ## Theming
 
-GeckoUI uses a powerful CSS variable-based theming system that automatically adapts all components when you change the theme class.
+GeckoUI uses [OKLCH](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value/oklch) color values with CSS custom properties (`--color-*`) powered by Tailwind CSS v4. You can override colors using **any CSS color format** — oklch, hex, rgb, hsl, etc.
 
-### Applying Themes
+### Dark Mode
 
-Simply add a theme class to your root element:
+Nothing switches on its own. Add the `dark` class above your app — normally `<html>` — or
+every component stays light:
 
 ```tsx
-// Light theme (default)
-<div className="light">
-  <App />
-</div>
-
-// Dark theme
-<div className="dark">
-  <App />
-</div>
-
-// Custom theme
-<div className="neon">
-  <App />
-</div>
+<html lang="en" className="dark">
 ```
 
-### Built-in Themes
-
-- **Light** (default) - Clean, bright interface
-- **Dark** - Easy on the eyes
+On a wrapper instead of the root, it themes only that subtree.
 
-### Creating Custom Themes
+### Customizing Colors
 
-Create a CSS file with your theme:
+Override CSS variables to match your brand:
 
 ```css
-/* my-theme.css */
-.my-theme {
-  /* Override any other CSS variables as needed */
+:root {
+  --color-primary-500: oklch(0.65 0.24 330);
+  --color-primary-600: oklch(0.55 0.22 330);
+
+  /* hex works too */
+  --color-primary-700: #6d28d9;
 }
 ```
 
-Import it and use it:
+Import after the base styles:
 
 ```tsx
-import "./my-theme.css";
+import "@geckoui/geckoui/styles.css";
 
-<div className="my-theme">
-  <App />
-</div>;
+import "./my-theme.css";
 ```
 
 ## Advanced Usage
 
-### Custom Styling with BEM
+### Custom Styling with Data Attributes
 
-All components use BEM (Block Element Modifier) naming for easy customization:
+Components use `data-*` attributes for variant/state styling:
 
 ```css
-/* Target specific component parts */
-.GeckoUIButton--contained-primary {
+/* Target specific variants */
+.GeckoUIButton[data-variant="filled"][data-color="primary"] {
   /* Your custom styles */
 }
 
@@ -148,6 +157,16 @@ All components are fully typed. Import types as needed:
 import type { ButtonProps, InputProps } from "@geckoui/geckoui";
 ```
 
+## AI Skills
+
+Install the GeckoUI skill to help AI assistants (Claude Code, etc.) generate accurate component code and themes:
+
+```
+npx skills add GeckoUI/skills
+```
+
+The skill provides component API references, theming variables, and class name mappings so AI agents can generate correct GeckoUI code without hallucination.
+
 ## License
 
 This project is licensed under the MIT License.