Skip to content

Commit 64e513b

Browse files
snwolaksnwolak
committed
update README and package descriptions for clarity; enhance documentation on core effects and usage
1 parent 6d27968 commit 64e513b

5 files changed

Lines changed: 94 additions & 10 deletions

File tree

‎README.md‎

Lines changed: 42 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,12 @@
11
# Protohiro Effects
22

3-
Protohiro Effects is a zero-wrapper React library for hard CSS effects like gradient borders, glass highlights, glow rings, noise overlays, and spotlight overlays.
3+
Protohiro Effects is a zero-wrapper React library for hard CSS effects on existing elements: gradient borders, spotlight reveal overlays, glass highlights, glow rings, and noise overlays.
4+
5+
Built for design systems and app UIs that need premium effects without extra DOM nodes, layout shifts, or runtime layout measurements.
46

57
## Live demo
68

7-
https://libs.protohiro.com/effects/
9+
[libs.protohiro.com/effects](https://libs.protohiro.com/effects/)
810

911
## Packages
1012

@@ -29,10 +31,32 @@ function Button() {
2931
}
3032
```
3133

34+
## Why this exists
35+
36+
Most visual effects are easy to prototype and annoying to ship. Hand-rolled CSS often turns into:
37+
38+
- extra wrapper elements
39+
- pseudo-element conflicts
40+
- broken `border-radius` clipping
41+
- SSR and hydration edge cases
42+
- Safari-specific fallback work
43+
44+
Protohiro Effects packages those effects as React hooks that mutate only `classList` and CSS custom properties on a single existing element.
45+
46+
## Best-fit use cases
47+
48+
- `react gradient border` without wrappers
49+
- `react spotlight reveal effect` on cards and CTAs
50+
- `react glass highlight` for premium dark surfaces
51+
- CSS effects for design systems and headless UI components
52+
- composable single-element effects that preserve refs
53+
3254
## Hooks
3355

3456
### `useGradientBorderEffect(options)`
3557

58+
Single-element gradient border with `border-radius` support and a graceful Safari fallback.
59+
3660
Options:
3761
- `thickness?: string | number`
3862
- `radius?: string | number`
@@ -58,6 +82,8 @@ Options:
5882

5983
### `useGlowEffect(options)`
6084

85+
Lightweight supporting glow for composition. Useful, but simpler than the core hard effects.
86+
6187
Options:
6288
- `color?: string`
6389
- `blur?: string | number`
@@ -67,13 +93,17 @@ Options:
6793

6894
### `useNoiseEffect(options)`
6995

96+
Noise overlay for textured surfaces and layered compositions.
97+
7098
Options:
7199
- `size?: string | number`
72100
- `intensity?: number`
73101
- `disabled?: boolean`
74102

75103
### `useSpotlightEffect(options)`
76104

105+
Interactive spotlight and reveal effect for premium cards, media, and CTA surfaces.
106+
77107
Options:
78108
- `mode?: 'glow' | 'reveal'`
79109
- `size?: string | number`
@@ -94,6 +124,16 @@ Options:
94124

95125
`gradient-border` uses `mask-composite` for the preferred ring rendering path. Safari fallback uses a simplified border and layered background. The fallback keeps content readable and does not hide element content.
96126

127+
## Positioning
128+
129+
This library is strongest when you need effects that are awkward to ship by hand:
130+
131+
- gradient borders with correct clipping
132+
- spotlight reveal overlays
133+
- subtle glass highlights on existing components
134+
135+
`glow` and `noise` are supporting effects. The main value is shipping the harder UI effects safely on a single element.
136+
97137
## Composability
98138

99139
Hooks are composable because each effect writes only namespaced classes (`pe-*`) and CSS variables (`--pe-*`).

‎packages/core/README.md‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,8 @@
22

33
Core runtime utilities used by `@protohiro/effects`.
44

5+
This package exists for the single-element runtime layer: style injection, class mutation, CSS variable mutation, and ref composition helpers for zero-wrapper effects.
6+
57
## Install
68

79
```bash
@@ -20,7 +22,7 @@ npm install @protohiro/effects-core
2022
- `toCssNumber`
2123

2224
Live demo:
23-
https://libs.protohiro.com/effects/
25+
[libs.protohiro.com/effects](https://libs.protohiro.com/effects/)
2426

2527
For full project docs and examples, see:
26-
https://github.com/protohiro-com/effects
28+
[github.com/protohiro-com/effects](https://github.com/protohiro-com/effects)

‎packages/core/package.json‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
{
22
"name": "@protohiro/effects-core",
33
"version": "0.1.3",
4-
"description": "Core runtime utilities for ProtoEffects CSS-first effects.",
4+
"description": "Core runtime utilities for zero-wrapper CSS effects and single-element DOM mutations.",
55
"license": "MIT",
66
"type": "module",
77
"main": "./dist/index.cjs",
@@ -21,7 +21,10 @@
2121
"css",
2222
"effects",
2323
"runtime",
24-
"utilities"
24+
"utilities",
25+
"zero-wrapper",
26+
"single-element",
27+
"css-variables"
2528
],
2629
"publishConfig": {
2730
"access": "public"

‎packages/react/README.md‎

Lines changed: 30 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,15 @@
11
# @protohiro/effects
22

3-
Zero-wrapper React hooks for composable CSS effects.
3+
React hooks for hard CSS effects on existing elements without wrappers.
4+
5+
Best for:
6+
7+
- `react gradient border`
8+
- `react spotlight reveal effect`
9+
- `react glass highlight`
10+
- composable effects in design systems
11+
12+
The library targets effects that are awkward to ship by hand because of pseudo-elements, `border-radius`, Safari fallback behavior, SSR, and ref composition.
413

514
## Install
615

@@ -19,6 +28,14 @@ export function Button() {
1928
}
2029
```
2130

31+
## Why use it
32+
33+
- no extra DOM nodes
34+
- no layout measurements
35+
- SSR and hydration friendly
36+
- preserves existing refs and class names
37+
- effects compose through namespaced classes and CSS variables
38+
2239
## Hooks
2340

2441
- `useGradientBorderEffect`
@@ -27,6 +44,16 @@ export function Button() {
2744
- `useNoiseEffect`
2845
- `useSpotlightEffect`
2946

47+
## Core effects
48+
49+
### `useGradientBorderEffect(options)`
50+
51+
Gradient border ring on a single existing element with `border-radius` support and graceful fallback behavior.
52+
53+
### `useSpotlightEffect(options)`
54+
55+
Interactive spotlight and reveal overlay for cards, media surfaces, and CTA blocks.
56+
3057
### `useGlassHighlightEffect(options)`
3158

3259
Adds a restrained glass highlight layer with edge light, soft sheen, tint, and optional backdrop blur for dark premium surfaces.
@@ -44,7 +71,7 @@ Options:
4471
- `disabled?: boolean`
4572

4673
Live demo:
47-
https://libs.protohiro.com/effects/
74+
[libs.protohiro.com/effects](https://libs.protohiro.com/effects/)
4875

4976
For full docs and demos, see:
50-
https://github.com/protohiro-com/effects
77+
[github.com/protohiro-com/effects](https://github.com/protohiro-com/effects)

‎packages/react/package.json‎

Lines changed: 13 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
{
22
"name": "@protohiro/effects",
33
"version": "0.3.1",
4-
"description": "Zero-wrapper React hooks for composable CSS effects.",
4+
"description": "React hooks for hard CSS effects like gradient borders, spotlight reveal, and glass highlights without wrappers.",
55
"license": "MIT",
66
"type": "module",
77
"main": "./dist/index.cjs",
@@ -26,9 +26,21 @@
2626
"react-hooks",
2727
"css-effects",
2828
"ui-effects",
29+
"hard-css-effects",
30+
"zero-wrapper",
31+
"no-wrapper",
32+
"single-element",
33+
"pseudo-element",
34+
"design-system-effects",
35+
"react-css-effects",
2936
"gradient-border",
37+
"react-gradient-border",
38+
"glass-highlight",
39+
"react-glass-effect",
3040
"glow",
3141
"spotlight",
42+
"spotlight-reveal",
43+
"react-spotlight",
3244
"noise-overlay",
3345
"design-system"
3446
],

0 commit comments

Comments
 (0)