medesign 0.0.0-stage → 1.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Metha Tripraphankit (Survey Engineering & Geoinformatics, Kasetsart University)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,223 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# ME-DESIGN v1.4.0
+
+**The Autonomous Design Engineering System & Quality Linter for AI Coding Assistants**
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![CI Matrix](https://github.com/methastrategy/medesign/actions/workflows/ci.yml/badge.svg)](https://github.com/methastrategy/medesign/actions/workflows/ci.yml)
+[![npm version](https://img.shields.io/npm/v/medesign.svg?color=emerald)](https://www.npmjs.com/package/medesign)
+[![Node Version](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg)](https://nodejs.org/)
+[![Status](https://img.shields.io/badge/status-production--ready-emerald.svg)]()
+[![Archetypes](https://img.shields.io/badge/archetypes-38%20models-indigo.svg)]()
+
+*Eliminate AI Slop and bring optical mathematics, perceptual color science, and mission-critical engineering rigor to automated UI/UX generation.*
+
+---
+
+</div>
+
+## 🌟 Why ME-DESIGN?
+
+Most AI-generated user interfaces suffer from **Decisionless Uniformity**: generic 3-card grids, oversaturated neon glows, clipping Thai/Latin font metrics, broken keyboard accessibility, and non-proportional press deformations.
+
+**ME-DESIGN** changes the paradigm from subjective aesthetic prompting to an **executable 5-Engine Design Architecture** coupled with a **Dual-Tier Quality Linter**, **Knowledge Discovery Search Engine**, and **Self-Healing Code Repair**.
+
+---
+
+## ⚔️ Multi-Dimensional Competitive Benchmark
+
+| Dimension | `medesign` (v1.4.0) | `ui-ux-pro-max-skill` | `pbakaus/impeccable` |
+| :--- | :--- | :--- | :--- |
+| **Execution Architecture** | **Autonomous Node.js CLI & Deterministic Engine** | Prompt-only System Text | Markdown Guidelines & Rules |
+| **Verification Gate** | **Mathematical Q-Score (0–100) + Hard Invariants** | Subjective LLM Self-Critique | Manual Inspection Checklist |
+| **Self-Healing Code Repair** | **Automatic AST/Regex Fixer (`medesign polish`)** | Re-prompting Prompt Loop | Manual Code Editing |
+| **Conversational Modifiers** | **Instant Code Density (`bolder` / `quiet`)** | Chat Revision Re-rolls | None |
+| **Knowledge Discovery** | **Pure Node.js Search across 38 Archetypes & Presets** | Static Markdown Reading | Static Document Browsing |
+| **Automated CI/CD Quality Gate** | **Native OASIS SARIF v2.1.0 for GitHub Code Scanning** | None | None |
+| **Perceptual Color Science** | **OKLCH / OKLab Gamut Mapping & `color-mix()`** | Standard Hex / sRGB Defaults | Hex / sRGB Recommendations |
+| **Headless Browser Matrix** | **Chrome DevTools Protocol (Real Contrast & 44px Hit-Targets)** | None | Manual Browser DevTools |
+| **Design Token Standards** | **Tailwind v4 `@theme`, W3C DTCG & CSS Custom Properties** | Unstructured CSS Snippets | None |
+| **Domain Archetype Depth** | **38 Decoupled Archetypes (HMI ISA-101, GIS Cadastre, Telemetry)** | Generic SaaS / E-commerce | General UI Polish Rules |
+| **Runtime Package Footprint** | **Zero-Dependency CLI (< 300 KB compressed on npm)** | Multi-file Prompt Repos | Docs / Repo Only |
+
+---
+
+## 🏛️ The 5-Engine Core Architecture
+
+```
+ME-DESIGN Core Engine
+├── 01. Optical Geometry Engine      -> Safe Concentric Radii, Area-Proportional Scaling, Hit Target Isolation
+├── 02. Perceptual Color Engine      -> OKLCH / OKLab Gamut, Dynamic color-mix(), Dark Mode Functional Tokens
+├── 03. Motion & Interaction Engine  -> 4 Behavioral Profiles (precision, soft-settle, spring-settle, instant)
+├── 04. Typography & Script Engine   -> Dual-Context Line-Height, Thai Diacritic Clearance, @font-face Calibration
+└── 05. Quality & Saliency Auditor   -> 4-Tier Governance, Task-Driven Attention Models, Zero-Compromise Gate
+```
+
+---
+
+## 📐 38 Production Archetypes (5-Axis Decoupled Matrix)
+
+ME-DESIGN decouples UI synthesis across 5 independent axes:
+**Operational Archetype × Visual Language × Spatial Model × Motion Profile × Governance Tier**
+
+- **Group A: Luxury & Editorial (01-05):** Quiet Luxury, Swiss International Editorial, Dark Haute Couture...
+- **Group B: SaaS, DevTools & High-Density (06-12):** Linear Minimal, Vercel Clean Monochrome, Bloomberg Pro Density, Raycast Spatial HUD...
+- **Group C: Fintech, Crypto & Glassmorphism (13-18):** Stripe Clean Gradient, Cyberpunk Matrix, Cosmos Acrylic Glass...
+- **Group D: Modern Consumer, E-Commerce & Brand (19-24):** Apple Pro Spatial, Airbnb Warm Domestic...
+- **Group E: Creative Agency & Experimental (25-30):** Neo-Brutalism, Kinetic Marquee, Biophilic Wellness...
+- **Group F: Mission-Critical Engineering & HMI (31-38):**
+  - **31. Mission Control HMI (ISA-101 Standard):** Tri-state alarms, greyscale base, operator decision priority.
+  - **32. Geospatial Situation Awareness (GIS & Cadastre):** Map-centric 16:10 / 100dvh, linked selection tables, EPSG coordinates.
+  - **33. CAD Precision Workbench:** Maximized canvas, floating command bar, geometric snap indicators.
+  - **34. Telemetry & Signal Forensics:** Time-series scrubbing, stale sensor detection, gap indicators.
+  - **35. Anomaly Triage & Incident Response:** Priority queue, severity vs confidence matrix.
+  - **36. Field Survey & Offline Operations:** 52px touch targets, RTK fix status, offline sync queue.
+  - **37. Spatiotemporal Change Detection:** Synchronized dual viewports, epoch time slider.
+  - **38. Data Provenance & Survey QA/QC:** Observation lineage, error ellipses, legal timestamp seals.
+
+---
+
+## 🚀 Quickstart: Running via `npx` (Zero Installation)
+
+Execute ME-DESIGN immediately without manual installation:
+
+```bash
+# 1. Discover archetypes, palettes, and typography for any domain query
+npx medesign search "cadastre survey"
+npx medesign search "apple hardware"
+npx medesign search "tesla telemetry"
+
+# 2. Self-healing code repair (auto-fixes MD005 focus rings, 100dvh, dead buttons, em-dashes)
+npx medesign polish path/to/index.html
+
+# 3. Fine-tune visual density and tone directly in code
+npx medesign bolder path/to/index.html   # Boost font weights, sharpen borders, raise contrast
+npx medesign quiet path/to/index.html    # Soften font weights, reduce borders to hairlines
+
+# 4. Lint an HTML, JSX, or CSS file with static AST & invariant rules
+npx medesign lint path/to/index.html
+
+# 5. Lint and export OASIS SARIF v2.1.0 for GitHub Code Scanning
+npx medesign lint path/to/index.html --format sarif
+
+# 6. Run headless Chrome DevTools Protocol verification matrix
+# (Computes real contrast ratios, tab focus indicators, and 44px hit-targets)
+npx medesign audit path/to/index.html
+
+# 7. Export design tokens to Tailwind CSS v4 @theme, W3C DTCG, or CSS variables
+npx medesign tokens --preset apple --format tailwind --out ./tokens
+
+# 8. Verify system health, Node.js version, and headless browser availability
+npx medesign doctor
+```
+
+### 🔎 Knowledge Discovery Engine (`medesign search`)
+
+Query the 38 production archetypes and design system presets to get immediate, actionable styling recommendations:
+
+```bash
+# Human-focused Terminal Summary Card
+npx medesign search "cadastre survey"
+
+# Output structured JSON for AI agent orchestration
+npx medesign search "luxury fintech" --json
+```
+
+```text
+ME-DESIGN Discovery Engine
+────────────────────────────────────────
+Query               "cadastre survey"
+Best Match          Archetype 38: Cadastral Survey & QA/QC Workbench
+Preset Link         metha (Metha Engineering Cockpit)
+
+DESIGN ARCHETYPE RECOMMENDATION
+  Archetype         Cadastral Survey & Data Provenance (38)
+  Spatial Model     16:10 / 100dvh Map-Centric with Split Data Grid
+  Primary Color     Electric Cyan (oklch(0.85 0.18 200))
+  Secondary Color   Passed Emerald (oklch(0.72 0.18 145))
+  Surface Contrast  Ultra-Dark Obsidian (#0a0d14)
+  Typography        JetBrains Mono + IBM Plex Sans Thai
+  Motion Profile    Precision Linear (120ms max)
+────────────────────────────────────────
+```
+
+### 🛠️ Self-Healing Code Repair (`medesign polish`)
+
+Automatically inspect and repair Hard Invariants in your HTML/CSS files without waiting for manual edits:
+
+- **MD005:** Injects physical `:focus-visible` outlines and `@media (forced-colors: active)` support when `box-shadow` is used without an outline.
+- **MD104:** Replaces unstable `100vh` on containers with dynamic `100dvh` (`min-height: 100vh; min-height: 100dvh;`).
+- **MD004:** Injects hover and active states for buttons without defined interactive contracts.
+- **MD002:** Adds `@media (prefers-reduced-motion)` accessibility gates.
+- **MD201:** Cleans up decorative AI-tell em-dashes `—` (including entity `&mdash;`) into clean hyphens `-`.
+
+```bash
+npx medesign polish path/to/dashboard.html
+```
+
+```text
+[POLISH COMPLETED] 3 issues automatically repaired in dashboard.html
+  Fixed: Replaced 1 raw 100vh with 100dvh fallback (MD104)
+  Fixed: Added physical focus outline & forced-colors high contrast (MD005)
+  Fixed: Cleaned 2 AI-tell em-dash punctuation & entities
+Q-Score: 91.3 -> 95.0 [PASS]
+```
+
+### ⚡ Visual Density Modifiers (`medesign bolder` & `medesign quiet`)
+
+Adjust visual weight, border contrast, and color vibrancy directly in your files:
+
+```bash
+# Elevate font weights (normal -> medium -> semibold -> bold), deepen border contrast, and boost OKLCH/Tailwind accent saturation
+npx medesign bolder path/to/dashboard.html
+
+# Soften font weights, convert borders to subtle hairlines, and shift OKLCH/Tailwind colors to a restrained minimalist palette
+npx medesign quiet path/to/dashboard.html
+```
+
+---
+
+### The Terminal Quality Audit Card
+
+```text
+ME-DESIGN v1.4.0
+Design Quality & Governance Audit
+────────────────────────────────────────
+Target        dashboard.tsx
+Archetype     Geospatial Situation Awareness (32)
+Analysis      Static AST & Semantic Rules
+Ruleset       medesign-standard@1.4.0
+
+QUALITY SCORE (Q = 0.30H + 0.25I + 0.20G + 0.15R + 0.10V)
+  Hierarchy (H)       94.0 / 100
+  Information (I)     90.0 / 100
+  Geometry (G)        92.0 / 100
+  Responsive (R)      88.0 / 100
+  Visual Craft (V)    95.0 / 100
+
+  Q-SCORE             91.8 / 100  [PASS]
+
+HARD INVARIANTS CHECKLIST
+  PASS  Keyboard Focus Ring Visibility (:focus-visible)
+  PASS  Reduced Motion Compliance (@media prefers-reduced-motion)
+  PASS  Anti-AI Tells: Zero Em-Dash Invariant
+  PASS  Predictable DOM Order (No unsemantic dense flow)
+
+────────────────────────────────────────
+RESULT: PASS (Exit Code: 0)
+```
+
+---
+
+## 🤖 AI Coding Assistant Integrations
+
+ME-DESIGN provides shared rule adapters for all major agentic tools:
+
+- **Claude Code:** Copy `integrations/claude-code/SKILL.md` to `.claude/skills/medesign/SKILL.md`
+- **Cursor:** Copy `integrations/cursor/medesign.mdc` to `.cursor/rules/medesign.mdc`
+- **Google Antigravity:** Native Skill supported under `skills/medesign/SKILL.md`
+
+---
+
+## 📄 License
+
+MIT License © 2026 Metha Triparamkit (Survey Engineering & Geoinformatics, Kasetsart University).