From ba4901e2508e4f1cc6738ae733ee8f1d84914957 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E1=84=8B=E1=85=B5=E1=84=90=E1=85=A2=E1=84=92=E1=85=AE?= =?UTF-8?q?=E1=86=AB?= Date: Mon, 3 Aug 2026 09:43:40 +0900 Subject: [PATCH] docs: highlight project capabilities --- README.md | 242 ++++++++++++++++++++++++++++++++---------------------- 1 file changed, 144 insertions(+), 98 deletions(-) diff --git a/README.md b/README.md index 25eb7b1..611b67e 100644 --- a/README.md +++ b/README.md @@ -8,6 +8,17 @@ Turn supported CSS into pixel art. Wrap one rendered HTML element with `` [Demo](https://react-pixel-ui.vercel.app) | [npm](https://www.npmjs.com/package/@react-pixel-ui/react) | [GitHub](https://github.com/Todari/react-pixel-ui) +![React Pixel UI — turn CSS into pixel art](https://react-pixel-ui.vercel.app/og.png) + +## Why React Pixel UI? + +- **Keep real DOM and CSS** — text, layout, events, and accessibility stay on the original element. +- **Use existing styles** — Tailwind, CSS modules, inline styles, gradients, borders, and shadows are read from computed CSS. +- **No Canvas dependency** — pixel art is generated with `clip-path`, RGBA PNG data URLs, and `drop-shadow()`. +- **SSR compatible** — elements render normally on the server and are enhanced after hydration. +- **Reactive by default** — style, class, theme, hover, focus, and active changes can be observed automatically. +- **Framework-independent core** — use `@react-pixel-ui/core` when you only need the CSS-to-pixel-art engine. + ## Install ```bash @@ -23,17 +34,19 @@ Requires **React 18+**. `@react-pixel-ui/core` is installed automatically. ## Quick Start ```tsx -import { Pixel } from '@react-pixel-ui/react'; +import { Pixel } from "@react-pixel-ui/react"; function App() { return ( -
+
Pixel Art!
@@ -65,13 +78,14 @@ import { Pixel } from '@react-pixel-ui/react'; ``` -| Prop | Type | Default | Description | -|------|------|---------|-------------| -| `size` | `number` | `4` | Pixel block size in CSS px. Larger = blockier. | -| `enabled` | `boolean` | `true` | Toggle pixelation on/off | +| Prop | Type | Default | Description | +| ---------- | -------------- | -------- | ---------------------------------------------------------------- | +| `size` | `number` | `4` | Pixel block size in CSS px. Larger = blockier. | +| `enabled` | `boolean` | `true` | Toggle pixelation on/off | | `children` | `ReactElement` | required | Single HTML element, or a component that forwards its ref to one | **Supported CSS properties:** + - `background` / `background-color` — solid colors and gradients (`linear-gradient`, `radial-gradient`, `repeating-*`). Alpha-preserving. - `border-radius` — converted to staircase corners (supports per-corner `[tl, tr, br, bl]`) - `border` — pixel art border with staircase corners. Box size is preserved via `border-color: transparent` (no layout shift, even with `box-sizing: content-box`). @@ -88,7 +102,7 @@ not cut it off. Existing parent filters are preserved, and multiple managed children share the parent safely. ```tsx -import { usePixelRef } from '@react-pixel-ui/react'; +import { usePixelRef } from "@react-pixel-ui/react"; function MyComponent() { const pixelRef = usePixelRef({ pixelSize: 6 }); @@ -97,9 +111,9 @@ function MyComponent() {
@@ -109,20 +123,20 @@ function MyComponent() { } ``` -| Option | Type | Default | Description | -|--------|------|---------|-------------| -| `pixelSize` | `number` | `4` | Pixel block size | -| `enabled` | `boolean` | `true` | Toggle pixelation | -| `observeHover` | `boolean` | `true` | Re-compute on `:hover` | -| `observeFocus` | `boolean` | `true` | Re-compute on `:focus` | -| `observeActive` | `boolean` | `true` | Re-compute on `:active` | +| Option | Type | Default | Description | +| --------------- | --------- | ------- | ----------------------- | +| `pixelSize` | `number` | `4` | Pixel block size | +| `enabled` | `boolean` | `true` | Toggle pixelation | +| `observeHover` | `boolean` | `true` | Re-compute on `:hover` | +| `observeFocus` | `boolean` | `true` | Re-compute on `:focus` | +| `observeActive` | `boolean` | `true` | Re-compute on `:active` | ### `PixelConfigProvider` — Global defaults Set default `pixelSize` for all `` and `usePixelRef` instances in the tree. ```tsx -import { PixelConfigProvider } from '@react-pixel-ui/react'; +import { PixelConfigProvider } from "@react-pixel-ui/react"; function App() { return ( @@ -134,17 +148,17 @@ function App() { } ``` -| Config Key | Type | Default | Description | -|------------|------|---------|-------------| -| `pixelSize` | `number` | `4` | Default pixel block size | -| `borderColor` | `string` | — | Default for `PixelBox`; CSS-reading APIs use the computed border color | +| Config Key | Type | Default | Description | +| ------------- | -------- | ------- | ---------------------------------------------------------------------- | +| `pixelSize` | `number` | `4` | Default pixel block size | +| `borderColor` | `string` | — | Default for `PixelBox`; CSS-reading APIs use the computed border color | ### `PixelBox` — Explicit props Use when you want direct control instead of auto-reading CSS. ```tsx -import { PixelBox } from '@react-pixel-ui/react'; +import { PixelBox } from "@react-pixel-ui/react"; Content - +; ``` -| Prop | Type | Default | Description | -|------|------|---------|-------------| -| `width` | `number` | `200` | Element width in px | -| `height` | `number` | `100` | Element height in px | -| `pixelSize` | `number` | `4` | Pixel block size | -| `borderRadius` | `number \| [number, number, number, number]` | — | Corner radius. Array = `[topLeft, topRight, bottomRight, bottomLeft]` | -| `borderWidth` | `number` | — | Border thickness (auto-snapped to pixelSize grid) | -| `borderColor` | `string` | — | Any CSS color | -| `background` | `string` | — | CSS color or gradient string | -| `shadow` | `{ x: number, y: number, color: string }` | — | Hard pixel shadow | -| `responsive` | `boolean` | `false` | Follow the size your CSS gives the box (detected via ResizeObserver) instead of `width`/`height` props. Size it with `style`/`className` (e.g. `style={{ width: '100%', height: 120 }}`). | +| Prop | Type | Default | Description | +| -------------- | -------------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `width` | `number` | `200` | Element width in px | +| `height` | `number` | `100` | Element height in px | +| `pixelSize` | `number` | `4` | Pixel block size | +| `borderRadius` | `number \| [number, number, number, number]` | — | Corner radius. Array = `[topLeft, topRight, bottomRight, bottomLeft]` | +| `borderWidth` | `number` | — | Border thickness (auto-snapped to pixelSize grid) | +| `borderColor` | `string` | — | Any CSS color | +| `background` | `string` | — | CSS color or gradient string | +| `shadow` | `{ x: number, y: number, color: string }` | — | Hard pixel shadow | +| `responsive` | `boolean` | `false` | Follow the size your CSS gives the box (detected via ResizeObserver) instead of `width`/`height` props. Size it with `style`/`className` (e.g. `style={{ width: '100%', height: 120 }}`). | `className`, `style`, and other HTML props always land on the **root** element — the wrapper `
` when a border is used. @@ -178,41 +192,43 @@ element — the wrapper `
` when a border is used. ### `PixelButton` — Pre-styled button ```tsx -import { PixelButton } from '@react-pixel-ui/react'; +import { PixelButton } from "@react-pixel-ui/react"; -Click me + + Click me +; ``` -| Prop | Type | Default | Description | -|------|------|---------|-------------| -| `variant` | `'primary' \| 'secondary' \| 'danger'` | `'primary'` | Color theme | -| `width` | `number` | `160` | Button width | -| `height` | `number` | `48` | Button height | -| `borderRadius` | `number` | `8` | Corner radius | -| `pixelSize` | `number` | from context | Pixel block size | -| `shadow` | `{ x, y, color }` | auto | Pixel shadow | +| Prop | Type | Default | Description | +| -------------- | -------------------------------------- | ------------ | ---------------- | +| `variant` | `'primary' \| 'secondary' \| 'danger'` | `'primary'` | Color theme | +| `width` | `number` | `160` | Button width | +| `height` | `number` | `48` | Button height | +| `borderRadius` | `number` | `8` | Corner radius | +| `pixelSize` | `number` | from context | Pixel block size | +| `shadow` | `{ x, y, color }` | auto | Pixel shadow | The rendered `