@musecat/uikit 0.1.1 → 0.1.3

package/.agents/references/Styles/Viewport.md

@@ -0,0 +1,42 @@
+# Viewport
+
+This document defines viewport mixin functions for easily writing media queries within SCSS.
+
+## Configuration
+
+Manages the breakpoint ranges (min, max, next) of `w1`, `w2`, `w3`, `w4` as a Map object.
+
+## Mixins
+
+- `@mixin viewport-max($max)`: Generates a max-width based media query
+- `@mixin viewport-min($min)`: Generates a min-width based media query
+- `@mixin viewport-between($min, $max)`: Generates a range-specified media query
+
+### Helper Mixins
+
+- `@mixin down($key)`: Applies at or below the max-width of a specific keyword (e.g., `w3`). Useful when writing mobile-first views.
+- `@mixin up($key)`: Applies at or above the min-width of a specific keyword. Useful when writing PC-first views.
+- `@mixin only($key)`: Applies exactly within the min ~ max range of a specific keyword.
+
+## Usage
+
+Import `_viewport.scss` as a module when designing custom components to control media queries.
+
+```scss
+@use "../../Styles/viewport" as vp;
+
+.container {
+  padding: 2rem;
+
+  @include vp.down(w3) {
+    // Applied on screens 767.98px or below
+    padding: 1rem;
+    flex-direction: column;
+  }
+
+  @include vp.only(w2) {
+    // Applied only on screens 320px ~ 409.98px
+    background: red;
+  }
+}
+```

package/AGENTS.md

@@ -0,0 +1,54 @@
+You are a concise coding assistant.
+
+## Stack
+
+- Primary stack: Next.js 16 + TypeScript.
+
+## Documentation References
+
+- Before using or modifying any component, framework, or style, you MUST read the corresponding documentation in `.agents/references/`.
+- **Documentation MUST Be Updated Immediately:** Every time you add, modify, or remove a component, framework, style, or any exported API/type, you MUST update the corresponding `.agents/references/` doc in the **same batch of tool calls** — not later, not after tests, not when asked. You must check what changed and update refs before moving to the next task.
+- If references have drifted from the actual code due to manual changes, analyze the source code and git history to align them.
+- **README Maintenance:** If you add, remove, or modify external package dependencies, you MUST update the Acknowledgements section in `README.md`.
+- **README Examples:** If the usage logic or APIs of core layout components (`View`, `Pressable`, `ImageView`) change, you MUST update the example code block in `README.md` to reflect those changes.
+
+## Test Failure Resolution
+
+When a test fails, do not blindly patch it to turn green. Reason about intent:
+1. Understand the component's design contract — what it should do vs. what it actually does.
+2. If the test correctly captures the intended behavior and the code violates it, fix the code.
+3. If the code correctly implements the intended behavior and the test reflects outdated assumptions, fix the test.
+4. If neither is clearly right, treat the component's source as the source of truth and align the test to match, unless you have explicit user instruction to change the behavior.
+
+## Design Token Enforcement
+
+- Theme design tokens (Radius, Color, Spacing, etc.) MUST be used at all times. Hardcoding raw pixel values, inline colors, or any literal style values instead of using the token system is strictly prohibited.
+
+## Theme & Token System Guidelines
+
+1. **Radius Scale Usage**
+   - Use standard tokens: `None`, `Light`, `Regular`, `Bold`, `ExtraBold`, `Heavy`, `Circle`.
+   - Explicit `cornerRadius` or directional radius arrays are supported.
+   - Centralized `RADIUS_TOKEN` mapping via `RadiusValue()` must be used.
+
+2. **Color & Paint Tokens**
+   - Palette colors must use the JSON expansion/SCSS mapping (e.g. `Red1TP3`, `BaseLight3`).
+   - Background props support state-specific mappings: `[idle, hover, active]`.
+   - Border props support paint tokens, width-only fallback (`Base1TP1`), and directional width arrays.
+   - Use `UISecondary` / `ReversedUISecondary` presets for default interactive element states (e.g., checked, selected).
+
+3. **Core Component Selection**
+   - Do not use raw HTML elements (`div`, `button`, `a`, `Link`) when custom layout blocks are available. `View` and `Pressable` are foundational primitives replacing these elements.
+   - Use `View` for structural layout. It dynamically resolves theme props, handles disabling/readonly state forwarding, and automatically applies `Squircle` clips when `radius` is present.
+   - Use `Pressable` for interactive elements. It renders polymorphic wrappers (button, a, Link, label) with proper radius resolution.
+   - **Layout & Sizing Defaults:** `View` and `Pressable` inherently use `display: flex` and support layout props like `gap`, `width`, and `height`.
+     - Numeric values for sizing/spacing props are automatically converted to `rem` values.
+     - For responsive or bounded sizing, use `min`, `max`, and `clamp` functions on `width` and `height` props.
+     - Avoid redundant inline styles or unnecessary utility classes by leveraging these built-in properties.
+- Package is published as `@musecat/uikit` on GitHub Packages. The root `index.ts` is the single entry point.
+   - **No internal barrels:** Directories must NOT contain `index.ts` re-exports. Always import from the definitive source file. The single exception is the root `index.ts` (npm package entry).
+   - **Type Referencing & Image:** Both components support various other props. You MUST refer to the TypeScript definitions of `View` and `Pressable` to check available attributes. For rendering images, use the custom `ImageView` component instead of the native `img` element.
+
+4. **Squircle & Motion Integration**
+   - `Squircle` renders SVG clip paths dynamically using `figma-squircle`.
+   - Avoid passing raw animate objects containing width/height directly to Framer Motion on Squircle elements to prevent base-style clip-path reset bugs. Use imperative controls (`useAnimationControls`) or animate wrapping wrappers instead.

package/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

package/README.md

@@ -36,6 +36,10 @@ export default function Example() {
 }
 ```
 
+## References
+
+This package includes `.agents/references/` directory with detailed documentation for every component, framework, and style system. Use it alongside TypeScript definitions as a guide when building with `@musecat/uikit`.
+
 ## Acknowledgements
 
 - [Motion (Framer Motion)](https://motion.dev/)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@musecat/uikit",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "private": false,
   "type": "module",
   "description": "High-performance Next.js React UI component library with Squircle shapes, theme tokens, and gesture-driven overlays",
@@ -34,6 +34,9 @@
   "files": [
     "index.ts",
     "packages/",
+    ".agents/",
+    "AGENTS.md",
+    "CLAUDE.md",
     "README.md",
     "LICENSE"
   ],

package/packages/Styles/_icon.scss

@@ -10,6 +10,8 @@ i,
 i::before,
 i::after,
 blockquote::before {
+  line-height: 1;
+  font-style: normal;
   font-family: var(--font-icon);
   font-variation-settings:
     "rond" 2,

package/packages/Styles/_importer.scss

@@ -1,7 +1,6 @@
 @use "animation";
 @use "color";
 @use "font";
-@use "icon";
 @use "system";
 @use "textstyle";
 @use "theme";