@pawn002/okca 0.0.1 → 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -21
- package/README.md +120 -120
- package/dist/transforms.js +4 -1
- package/package.json +42 -42
package/LICENSE
CHANGED
|
@@ -1,21 +1,21 @@
|
|
|
1
|
-
MIT License
|
|
2
|
-
|
|
3
|
-
Copyright (c) 2026 John Z. Rioflorido
|
|
4
|
-
|
|
5
|
-
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
-
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
-
in the Software without restriction, including without limitation the rights
|
|
8
|
-
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
-
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
-
furnished to do so, subject to the following conditions:
|
|
11
|
-
|
|
12
|
-
The above copyright notice and this permission notice shall be included in all
|
|
13
|
-
copies or substantial portions of the Software.
|
|
14
|
-
|
|
15
|
-
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
-
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
-
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
-
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
-
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
-
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
-
SOFTWARE.
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 John Z. Rioflorido
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,120 +1,120 @@
|
|
|
1
|
-
# okca — OK Contrast Algorithm
|
|
2
|
-
|
|
3
|
-
OKLCH-native contrast ratio with **zero false passes** against WCAG 2.x.
|
|
4
|
-
|
|
5
|
-
OKCA outputs ratios on the familiar 1–21 scale with the same AA (4.5) and AAA (7.0) thresholds as WCAG. Drop-in replacement for WCAG contrast — same numbers for achromatic pairs, stricter for saturated chromatic colors.
|
|
6
|
-
|
|
7
|
-
## Install
|
|
8
|
-
|
|
9
|
-
```bash
|
|
10
|
-
npm install okca
|
|
11
|
-
```
|
|
12
|
-
|
|
13
|
-
## Usage
|
|
14
|
-
|
|
15
|
-
```ts
|
|
16
|
-
import { calculateContrast } from 'okca';
|
|
17
|
-
|
|
18
|
-
calculateContrast('#ffffff', '#000000'); // 21
|
|
19
|
-
calculateContrast('#fff', '#767676'); // 4.5 — WCAG AA boundary anchor
|
|
20
|
-
calculateContrast('#ff69b4', '#1a1a1a'); // ~4.0 (WCAG gives 6.6 — a known false pass)
|
|
21
|
-
```
|
|
22
|
-
|
|
23
|
-
Or use the class:
|
|
24
|
-
|
|
25
|
-
```ts
|
|
26
|
-
import { OkcaService } from 'okca';
|
|
27
|
-
|
|
28
|
-
const okca = new OkcaService();
|
|
29
|
-
okca.calculateContrast('#fff', '#000'); // 21
|
|
30
|
-
```
|
|
31
|
-
|
|
32
|
-
Accepts
|
|
33
|
-
|
|
34
|
-
## What OKCA solves
|
|
35
|
-
|
|
36
|
-
WCAG 2.x contrast has two well-documented failure modes:
|
|
37
|
-
|
|
38
|
-
1. **False passes for saturated chromatic text.** Hot pink on near-black scores 6.6:1 under WCAG — a comfortable AA pass — but is demonstrably harder to read than achromatic pairs at equivalent luminance.
|
|
39
|
-
|
|
40
|
-
2. **False passes for green hues near the AA boundary.** OKLCH L³ (the perceptually uniform luminance proxy) underestimates WCAG Y for greens because sRGB weights green at 71.5%. A pair that WCAG rates 4.4 can appear to score 4.7 when uncorrected.
|
|
41
|
-
|
|
42
|
-
OKCA corrects both while guaranteeing **FP = 0** — OKCA never approves a pair that WCAG rejects.
|
|
43
|
-
|
|
44
|
-
## Algorithm
|
|
45
|
-
|
|
46
|
-
OKCA uses OKLCH L³ as a luminance proxy (L cubed ≈ WCAG Y for neutral grays), with two targeted corrections:
|
|
47
|
-
|
|
48
|
-
### 1. Chroma compression on lighter element
|
|
49
|
-
|
|
50
|
-
Saturated lighter colors get a power-compression penalty proportional to their Oklab chroma:
|
|
51
|
-
|
|
52
|
-
```
|
|
53
|
-
C = sqrt(a² + b²) // Oklab chroma
|
|
54
|
-
satW = min(1, (C / 0.15)²) // quadratic ramp: 0 at C=0, 1 at C≥0.15
|
|
55
|
-
exp = 1 + 0.75 × satW // 1.0 (achromatic) … 1.75 (fully saturated)
|
|
56
|
-
lighterY = (lighterL ^ exp) ^ 3
|
|
57
|
-
```
|
|
58
|
-
|
|
59
|
-
Effect: reduces the ratio for saturated lighter elements. Achromatic colors are unaffected.
|
|
60
|
-
|
|
61
|
-
### 2. Green correction on darker element
|
|
62
|
-
|
|
63
|
-
For darker elements with Oklab `a < -0.05` (true greens), a correction increases the luminance proxy to match WCAG Y:
|
|
64
|
-
|
|
65
|
-
```
|
|
66
|
-
correction = 0.155 × (-a - 0.05)
|
|
67
|
-
Leff = min(1, darkerL + correction)
|
|
68
|
-
darkerY = Leff³
|
|
69
|
-
```
|
|
70
|
-
|
|
71
|
-
Effect: increases the denominator → lowers the ratio, preventing green false passes.
|
|
72
|
-
|
|
73
|
-
### Output
|
|
74
|
-
|
|
75
|
-
```
|
|
76
|
-
ratio = (lighterY + 0.05) / (darkerY + 0.05)
|
|
77
|
-
```
|
|
78
|
-
|
|
79
|
-
Clamped to [1, 21], rounded to 1 decimal place.
|
|
80
|
-
|
|
81
|
-
## FP = 0 guarantee
|
|
82
|
-
|
|
83
|
-
- Step 1 can only *reduce* the numerator (lighter element penalty) → lower ratio
|
|
84
|
-
- Step 2 can only *increase* the denominator (green correction) → lower ratio
|
|
85
|
-
- Therefore: `ratio_OKCA ≤ ratio_WCAG` for any input pair
|
|
86
|
-
|
|
87
|
-
A pair that fails WCAG will also fail OKCA. **Zero false passes by construction.**
|
|
88
|
-
|
|
89
|
-
## Key constants
|
|
90
|
-
|
|
91
|
-
| Constant | Value | Role |
|
|
92
|
-
|----------|------:|------|
|
|
93
|
-
| `C_THRESH` | 0.15 | Oklab chroma at which lighter-element penalty is fully active |
|
|
94
|
-
| `CHROMA_K` | 0.75 | Maximum additional power exponent at full saturation |
|
|
95
|
-
| `K_DARK` | 0.155 | Green correction coefficient on darker element |
|
|
96
|
-
| `A_THRESH` | 0.05 | Oklab `a` gate: green correction fires only when `a < -0.05` |
|
|
97
|
-
|
|
98
|
-
## Properties
|
|
99
|
-
|
|
100
|
-
- **Achromatic exactness:** white/black = 21, white/#767676 = 4.5 — matches WCAG exactly
|
|
101
|
-
- **Symmetric:** `okca(A, B) = okca(B, A)` — order doesn't matter
|
|
102
|
-
- **
|
|
103
|
-
- **Clean-room implementation:** no third-party contrast algorithm source code
|
|
104
|
-
|
|
105
|
-
## Validation
|
|
106
|
-
|
|
107
|
-
Tested against 2,587 color pairs across three batteries (light-on-dark, dark-on-light, design systems from Tailwind/Material/Radix):
|
|
108
|
-
|
|
109
|
-
| Battery | Pairs | False Passes | False Failures |
|
|
110
|
-
|---------|------:|:------------:|:--------------:|
|
|
111
|
-
| Light-on-dark | 53 | 0 | 1 |
|
|
112
|
-
| Dark-on-light | 54 | 0 | 0 |
|
|
113
|
-
| Design systems | 2,480 | 0 | 28 |
|
|
114
|
-
| **Total** | **2,587** | **0** | **29** |
|
|
115
|
-
|
|
116
|
-
All false failures are warm saturated hues (red, fuchsia, pink) — principled conservatism, not miscalibration.
|
|
117
|
-
|
|
118
|
-
## License
|
|
119
|
-
|
|
120
|
-
MIT
|
|
1
|
+
# okca — OK Contrast Algorithm
|
|
2
|
+
|
|
3
|
+
OKLCH-native contrast ratio with **zero false passes** against WCAG 2.x.
|
|
4
|
+
|
|
5
|
+
OKCA outputs ratios on the familiar 1–21 scale with the same AA (4.5) and AAA (7.0) thresholds as WCAG. Drop-in replacement for WCAG contrast — same numbers for achromatic pairs, stricter for saturated chromatic colors.
|
|
6
|
+
|
|
7
|
+
## Install
|
|
8
|
+
|
|
9
|
+
```bash
|
|
10
|
+
npm install okca
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
## Usage
|
|
14
|
+
|
|
15
|
+
```ts
|
|
16
|
+
import { calculateContrast } from 'okca';
|
|
17
|
+
|
|
18
|
+
calculateContrast('#ffffff', '#000000'); // 21
|
|
19
|
+
calculateContrast('#fff', '#767676'); // 4.5 — WCAG AA boundary anchor
|
|
20
|
+
calculateContrast('#ff69b4', '#1a1a1a'); // ~4.0 (WCAG gives 6.6 — a known false pass)
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
Or use the class:
|
|
24
|
+
|
|
25
|
+
```ts
|
|
26
|
+
import { OkcaService } from 'okca';
|
|
27
|
+
|
|
28
|
+
const okca = new OkcaService();
|
|
29
|
+
okca.calculateContrast('#fff', '#000'); // 21
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
Accepts 3- and 6-digit hex strings (e.g. `#fff`, `#ff8000`).
|
|
33
|
+
|
|
34
|
+
## What OKCA solves
|
|
35
|
+
|
|
36
|
+
WCAG 2.x contrast has two well-documented failure modes:
|
|
37
|
+
|
|
38
|
+
1. **False passes for saturated chromatic text.** Hot pink on near-black scores 6.6:1 under WCAG — a comfortable AA pass — but is demonstrably harder to read than achromatic pairs at equivalent luminance.
|
|
39
|
+
|
|
40
|
+
2. **False passes for green hues near the AA boundary.** OKLCH L³ (the perceptually uniform luminance proxy) underestimates WCAG Y for greens because sRGB weights green at 71.5%. A pair that WCAG rates 4.4 can appear to score 4.7 when uncorrected.
|
|
41
|
+
|
|
42
|
+
OKCA corrects both while guaranteeing **FP = 0** — OKCA never approves a pair that WCAG rejects.
|
|
43
|
+
|
|
44
|
+
## Algorithm
|
|
45
|
+
|
|
46
|
+
OKCA uses OKLCH L³ as a luminance proxy (L cubed ≈ WCAG Y for neutral grays), with two targeted corrections:
|
|
47
|
+
|
|
48
|
+
### 1. Chroma compression on lighter element
|
|
49
|
+
|
|
50
|
+
Saturated lighter colors get a power-compression penalty proportional to their Oklab chroma:
|
|
51
|
+
|
|
52
|
+
```
|
|
53
|
+
C = sqrt(a² + b²) // Oklab chroma
|
|
54
|
+
satW = min(1, (C / 0.15)²) // quadratic ramp: 0 at C=0, 1 at C≥0.15
|
|
55
|
+
exp = 1 + 0.75 × satW // 1.0 (achromatic) … 1.75 (fully saturated)
|
|
56
|
+
lighterY = (lighterL ^ exp) ^ 3
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
Effect: reduces the ratio for saturated lighter elements. Achromatic colors are unaffected.
|
|
60
|
+
|
|
61
|
+
### 2. Green correction on darker element
|
|
62
|
+
|
|
63
|
+
For darker elements with Oklab `a < -0.05` (true greens), a correction increases the luminance proxy to match WCAG Y:
|
|
64
|
+
|
|
65
|
+
```
|
|
66
|
+
correction = 0.155 × (-a - 0.05)
|
|
67
|
+
Leff = min(1, darkerL + correction)
|
|
68
|
+
darkerY = Leff³
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
Effect: increases the denominator → lowers the ratio, preventing green false passes.
|
|
72
|
+
|
|
73
|
+
### Output
|
|
74
|
+
|
|
75
|
+
```
|
|
76
|
+
ratio = (lighterY + 0.05) / (darkerY + 0.05)
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
Clamped to [1, 21], rounded to 1 decimal place.
|
|
80
|
+
|
|
81
|
+
## FP = 0 guarantee
|
|
82
|
+
|
|
83
|
+
- Step 1 can only *reduce* the numerator (lighter element penalty) → lower ratio
|
|
84
|
+
- Step 2 can only *increase* the denominator (green correction) → lower ratio
|
|
85
|
+
- Therefore: `ratio_OKCA ≤ ratio_WCAG` for any input pair
|
|
86
|
+
|
|
87
|
+
A pair that fails WCAG will also fail OKCA. **Zero false passes by construction.**
|
|
88
|
+
|
|
89
|
+
## Key constants
|
|
90
|
+
|
|
91
|
+
| Constant | Value | Role |
|
|
92
|
+
|----------|------:|------|
|
|
93
|
+
| `C_THRESH` | 0.15 | Oklab chroma at which lighter-element penalty is fully active |
|
|
94
|
+
| `CHROMA_K` | 0.75 | Maximum additional power exponent at full saturation |
|
|
95
|
+
| `K_DARK` | 0.155 | Green correction coefficient on darker element |
|
|
96
|
+
| `A_THRESH` | 0.05 | Oklab `a` gate: green correction fires only when `a < -0.05` |
|
|
97
|
+
|
|
98
|
+
## Properties
|
|
99
|
+
|
|
100
|
+
- **Achromatic exactness:** white/black = 21, white/#767676 = 4.5 — matches WCAG exactly
|
|
101
|
+
- **Symmetric:** `okca(A, B) = okca(B, A)` — order doesn't matter
|
|
102
|
+
- **Zero dependencies:** pure TypeScript, no runtime deps
|
|
103
|
+
- **Clean-room implementation:** no third-party contrast algorithm source code
|
|
104
|
+
|
|
105
|
+
## Validation
|
|
106
|
+
|
|
107
|
+
Tested against 2,587 color pairs across three batteries (light-on-dark, dark-on-light, design systems from Tailwind/Material/Radix):
|
|
108
|
+
|
|
109
|
+
| Battery | Pairs | False Passes | False Failures |
|
|
110
|
+
|---------|------:|:------------:|:--------------:|
|
|
111
|
+
| Light-on-dark | 53 | 0 | 1 |
|
|
112
|
+
| Dark-on-light | 54 | 0 | 0 |
|
|
113
|
+
| Design systems | 2,480 | 0 | 28 |
|
|
114
|
+
| **Total** | **2,587** | **0** | **29** |
|
|
115
|
+
|
|
116
|
+
All false failures are warm saturated hues (red, fuchsia, pink) — principled conservatism, not miscalibration.
|
|
117
|
+
|
|
118
|
+
## License
|
|
119
|
+
|
|
120
|
+
MIT
|
package/dist/transforms.js
CHANGED
|
@@ -24,7 +24,10 @@ function linearize(c) {
|
|
|
24
24
|
function hexToSrgb(hex) {
|
|
25
25
|
if (!hex.startsWith('#'))
|
|
26
26
|
return null;
|
|
27
|
-
|
|
27
|
+
let h = hex.slice(1);
|
|
28
|
+
if (/^[0-9A-Fa-f]{3}$/.test(h)) {
|
|
29
|
+
h = h[0] + h[0] + h[1] + h[1] + h[2] + h[2];
|
|
30
|
+
}
|
|
28
31
|
if (!/^[0-9A-Fa-f]{6}$/.test(h))
|
|
29
32
|
return null;
|
|
30
33
|
return [
|
package/package.json
CHANGED
|
@@ -1,42 +1,42 @@
|
|
|
1
|
-
{
|
|
2
|
-
"name": "@pawn002/okca",
|
|
3
|
-
"version": "0.0
|
|
4
|
-
"description": "OK Contrast Algorithm — OKLCH-native, WCAG-compatible contrast ratio with zero false passes",
|
|
5
|
-
"author": "John Z. Rioflorido",
|
|
6
|
-
"main": "./dist/index.js",
|
|
7
|
-
"types": "./dist/index.d.ts",
|
|
8
|
-
"files": ["dist"],
|
|
9
|
-
"scripts": {
|
|
10
|
-
"build": "tsc",
|
|
11
|
-
"test": "jest"
|
|
12
|
-
},
|
|
13
|
-
"devDependencies": {
|
|
14
|
-
"colorjs.io": "^0.5.2",
|
|
15
|
-
"@types/jest": "^29.5.14",
|
|
16
|
-
"jest": "^29.7.0",
|
|
17
|
-
"ts-jest": "^29.2.5",
|
|
18
|
-
"typescript": "^5.7.2"
|
|
19
|
-
},
|
|
20
|
-
"repository": {
|
|
21
|
-
"type": "git",
|
|
22
|
-
"url": "https://github.com/pawn002/okca.git"
|
|
23
|
-
},
|
|
24
|
-
"homepage": "https://github.com/pawn002/okca",
|
|
25
|
-
"bugs": {
|
|
26
|
-
"url": "https://github.com/pawn002/okca/issues"
|
|
27
|
-
},
|
|
28
|
-
"license": "MIT",
|
|
29
|
-
"keywords": [
|
|
30
|
-
"contrast",
|
|
31
|
-
"accessibility",
|
|
32
|
-
"a11y",
|
|
33
|
-
"oklch",
|
|
34
|
-
"wcag",
|
|
35
|
-
"color",
|
|
36
|
-
"perceptual",
|
|
37
|
-
"okca"
|
|
38
|
-
],
|
|
39
|
-
"engines": {
|
|
40
|
-
"node": ">=18.0.0"
|
|
41
|
-
}
|
|
42
|
-
}
|
|
1
|
+
{
|
|
2
|
+
"name": "@pawn002/okca",
|
|
3
|
+
"version": "0.1.0",
|
|
4
|
+
"description": "OK Contrast Algorithm — OKLCH-native, WCAG-compatible contrast ratio with zero false passes",
|
|
5
|
+
"author": "John Z. Rioflorido",
|
|
6
|
+
"main": "./dist/index.js",
|
|
7
|
+
"types": "./dist/index.d.ts",
|
|
8
|
+
"files": ["dist"],
|
|
9
|
+
"scripts": {
|
|
10
|
+
"build": "tsc",
|
|
11
|
+
"test": "jest"
|
|
12
|
+
},
|
|
13
|
+
"devDependencies": {
|
|
14
|
+
"colorjs.io": "^0.5.2",
|
|
15
|
+
"@types/jest": "^29.5.14",
|
|
16
|
+
"jest": "^29.7.0",
|
|
17
|
+
"ts-jest": "^29.2.5",
|
|
18
|
+
"typescript": "^5.7.2"
|
|
19
|
+
},
|
|
20
|
+
"repository": {
|
|
21
|
+
"type": "git",
|
|
22
|
+
"url": "https://github.com/pawn002/okca.git"
|
|
23
|
+
},
|
|
24
|
+
"homepage": "https://github.com/pawn002/okca",
|
|
25
|
+
"bugs": {
|
|
26
|
+
"url": "https://github.com/pawn002/okca/issues"
|
|
27
|
+
},
|
|
28
|
+
"license": "MIT",
|
|
29
|
+
"keywords": [
|
|
30
|
+
"contrast",
|
|
31
|
+
"accessibility",
|
|
32
|
+
"a11y",
|
|
33
|
+
"oklch",
|
|
34
|
+
"wcag",
|
|
35
|
+
"color",
|
|
36
|
+
"perceptual",
|
|
37
|
+
"okca"
|
|
38
|
+
],
|
|
39
|
+
"engines": {
|
|
40
|
+
"node": ">=18.0.0"
|
|
41
|
+
}
|
|
42
|
+
}
|