@musecat/uikit 0.1.1 → 0.1.3

package/.agents/references/Frameworks/Theme.md

@@ -0,0 +1,68 @@
+# Theme Framework
+
+## Purpose
+
+The `Theme` framework is a set of utilities and types that receive UIKit's design system tokens (color, background, border, shadow, blur, etc.) as React props and convert them into corresponding CSS classes. It plays a central role in maintaining global theme-based consistency.
+
+## Usage Logic
+
+- **Radius**: `Radius.types.ts` returns strings like "R8", "Circle" as pixels or CSS variables.
+- **Color/Background**: The `resolveThemeClasses` function combines the given preset (`themePreset`), background (`background`), and text color (`color`) to infer class names and returns them as an array.
+- **Border / Shadow / Blur**: Each mapping function converts into utility classes like `ThemeBorder-`, `ThemeShadow-`, `BackgroundBlur-`.
+
+## Type Signatures
+
+```typescript
+// Theme.types.ts
+export type ThemePreset =
+  "UIPrimary" | "UISecondary" | "BaseFull" | "BaseSoft"; /* ... */
+export type ThemePaint =
+  | `${ThemeColorName}${ThemeLevel}`
+  | `${ThemeColorName}${ThemeLevel}TP${ThemeTPScale}`;
+
+export interface ThemeSystemProps {
+  themePreset?: ThemePreset;
+  background?: ThemeBackgroundPaint;
+  color?: ThemePaint;
+  border?: ThemeBorderPaint;
+  shadow?: ThemeShadow;
+  themeInteractive?: boolean;
+  selected?: boolean;
+  disabled?: boolean;
+  readOnly?: boolean;
+  backgroundBlur?: BackgroundBlurValue;
+
+}
+
+export function resolveThemeClasses(
+  props: ThemeSystemProps & {/* ... */},
+): string[];
+export function Border(
+  border?: ThemeBorderPaint,
+  basePaint?: ThemePaint,
+): string | undefined;
+export function Shadow(shadow?: ThemeShadow): string | undefined;
+```
+
+## Example Code
+
+```tsx
+import {
+  resolveThemeClasses,
+  Border,
+  Shadow,
+} from "@/packages/Frameworks/Theme/Theme.types";
+import clsx from "clsx";
+
+function CustomBox(props: ThemeSystemProps) {
+  const themeClasses = resolveThemeClasses(props);
+  const borderClass = Border(props.border);
+  const shadowClass = Shadow(props.shadow);
+
+  return (
+    <div className={clsx(themeClasses, borderClass, shadowClass)}>
+      Box with theme applied
+    </div>
+  );
+}
+```

package/.agents/references/Frameworks/Toaster.md

@@ -0,0 +1,67 @@
+# Toaster Framework
+
+## Purpose
+
+The `Toaster` framework is a wrapper component for displaying toast messages (notifications) used throughout the application. It internally uses the `sonner` library and provides custom styles and default icon settings tailored to UIKit's design system (icons, color mode, etc.).
+
+## Usage Logic
+
+- Render `ToasterBootstrap` (default export) at the top level (Root Layout, etc.).
+- Where you need to show a toast message, use the `toast` object re-exported from the `sonner` package to trigger messages.
+- Automatically injects UIKit's color mode and custom icons (`Icon` component) to maintain application consistency.
+
+## Type Signatures
+
+```typescript
+import type { IconProps } from "../../Components/Icon/Icon.types";
+import type { ToasterProps } from "sonner";
+
+export interface ToasterBootstrapProps extends ToasterProps {
+  "data-color-mode"?: string;
+  theme?: ToasterProps["theme"];
+  icon?: IconProps;
+  title?: React.ReactNode;
+  storage?: {
+    key?: string;
+    value?: string;
+  }[];
+}
+
+
+```
+
+## Example Code
+
+```tsx
+// 1. Render at the top level (App component, etc.)
+import ToasterBootstrap from "@/packages/Frameworks/Toaster/Toaster.boot";
+
+export default function App() {
+  return (
+    <>
+      <ToasterBootstrap data-color-mode="dark" />
+      <MyComponents />
+    </>
+  );
+}
+
+// 2. Show toast
+import { toast } from "@/packages/Frameworks/Toaster/Toaster.boot";
+
+function MyComponents() {
+  const handleSuccess = () => {
+    toast.success("Saved successfully.");
+  };
+
+  const handleError = () => {
+    toast.error("An error occurred.");
+  };
+
+  return (
+    <div>
+      <button onClick={handleSuccess}>Success</button>
+      <button onClick={handleError}>Fail</button>
+    </div>
+  );
+}
+```

package/.agents/references/Frameworks/View.md

@@ -0,0 +1,81 @@
+# View Framework
+
+## Purpose
+
+The `View` framework is UIKit's core layout building block. It replaces React's `div` or `motion.div` to help you declaratively and consistently write Flexbox and Grid layouts, themes, corner rounding (Squircle), padding/margin, blur, and other style properties. It also provides sub-components like `HScroll`, `Image`, and `DND`.
+
+## Usage Logic
+
+- The `alignItems`, `justifyContent`, `column`, `row`, `gap` shorthand props make Flexbox layout easy to compose.
+- When `radius` is specified, it is rendered using the `Squircle` framework by default, except when `noSquircle` is `true` or there is a border.
+- Passing the `motion` prop internally converts it into `motion/react`'s animation component.
+- Sub-components like `View.DND` are provided as a namespace to maintain a consistent mental model.
+
+## Type Signatures
+
+```typescript
+import type { CSSProperties, HTMLAttributes } from "react";
+import type { MotionProps } from "motion/react";
+import type { WindProps } from "../_shared/Wind.types";
+import type {
+  PaddingProps,
+  RadiusProps,
+  ThemeSystemProps,
+  BorderProps,
+} from "../Theme";
+
+export interface ViewProps
+  extends
+    HTMLAttributes<HTMLDivElement>,
+    WindProps,
+    ThemeSystemProps,
+    BorderProps,
+    RadiusProps,
+    PaddingProps {
+  motion?: MotionProps;
+  alignItems?: CSSProperties["alignItems"];
+  justifyContent?: CSSProperties["justifyContent"];
+  wrap?: CSSProperties["flexWrap"];
+  column?: boolean;
+  row?: boolean;
+  inline?: boolean;
+  gap?: number | string;
+  gridTemplateColumns?: string;
+  gridTemplateRows?: string;
+  gridAutoFlow?: CSSProperties["gridAutoFlow"];
+  fullWidth?: boolean;
+  width?: number | string;
+  height?: number | string;
+  margin?: number | string;
+  sticky?: boolean | number | string;
+  top?: number | string;
+  bottom?: number | string;
+  noSquircle?: boolean; // option to bypass Squircle rendering
+}
+```
+
+## Example Code
+
+```tsx
+import View from "@/packages/Frameworks/View/View";
+
+function Card() {
+  return (
+    <View
+      column
+      gap={16}
+      padding="R24"
+      radius="R16"
+      themePreset="UIPrimary"
+      width="100%"
+    >
+      <View row alignItems="center" justifyContent="space-between">
+        <h3>Title</h3>
+        <button>Action</button>
+      </View>
+
+      <View opacity={0.8}>Content goes here.</View>
+    </View>
+  );
+}
+```

package/.agents/references/Frameworks/_shared.md

@@ -0,0 +1,74 @@
+# _shared Framework
+
+## Purpose
+
+The `_shared` framework folder is a module that collects utility functions, hooks, constants, and shared types commonly depended on by multiple frameworks or components. It includes size conversion, layer constants, scroll lock handling, share layout type definitions, etc.
+
+## Usage Logic
+
+- **sizing.ts**: Consistently parses numeric or string size values like `16`, `"1rem"`, `"16px"` and converts them to CSS values (`Size`, `SizePX` functions).
+- **Padding.types.ts**: Utilities for handling multi-directional padding (vertical/horizontal, single).
+- **useControllableState.ts**: A custom hook to support both controlled and uncontrolled component states.
+- **layer.constants.ts**: Provides global Z-index layer constants (`LAYER_Z_INDEX`).
+- **Wind.types.ts**: Shared layout props (`width`, `height`, `margin`, `gap`, `alignItems`, `justifyContent`, `alignSelf`, `column`, `row`, `fullWidth`, `opacity`, `noSquircle`) used by both `ViewProps` and `PressableProps`.
+- **bodyScrollLock.ts**: Implements touch and mouse scroll lock.
+- **normalize.ts**: Image src, brand icon class, and language name normalization utilities.
+
+## Type Signatures
+
+```typescript
+// sizing.ts
+export type UIKitSizeValue = number | string;
+export function Size(value?: UIKitSizeValue | null): string | number | undefined;
+export function SizePX(value: UIKitSizeValue | undefined, fallback: number, rootFontSize?: number): number;
+
+// useControllableState.ts
+export function useControllableState<T>(options: { value?: T; defaultValue: T }): const [T, (nextValue: T | ((prevValue: T) => T)) => void, boolean];
+
+// layer.constants.ts
+export const LAYER_Z_INDEX: { popover: number, modal: number, /* ... */ };
+
+// Wind.types.ts
+export interface WindProps {
+  width?: number | string;
+  height?: number | string;
+  margin?: number | string;
+  gap?: number | string;
+  alignItems?: CSSProperties["alignItems"];
+  justifyContent?: CSSProperties["justifyContent"];
+  alignSelf?: CSSProperties["alignSelf"];
+  column?: boolean;
+  row?: boolean;
+  fullWidth?: boolean;
+  opacity?: number;
+  noSquircle?: boolean;
+}
+
+// bodyScrollLock.ts
+export function useScrollLock(locked?: boolean): { lockScroll: () => void, openScroll: () => void };
+```
+
+## Example Code
+
+```tsx
+import { Size } from "@/packages/Frameworks/_shared/sizing";
+import { useScrollLock } from "@/packages/Frameworks/_shared/bodyScrollLock";
+import { useControllableState } from "@/packages/Frameworks/_shared/useControllableState";
+
+function MyComponent({ value, defaultValue, width }) {
+  // Scroll lock
+  useScrollLock(true);
+
+  // Size normalization: 16 -> "1.6rem"
+  const widthStyle = Size(width);
+
+  // State management (controlled or uncontrolled)
+  const [current, setCurrent] = useControllableState({ value, defaultValue });
+
+  return (
+    <div style={{ width: widthStyle }}>
+      <button onClick={() => setCurrent(!current)}>Toggle</button>
+    </div>
+  );
+}
+```

package/.agents/references/Styles/Animation.md

@@ -0,0 +1,43 @@
+# Animation
+
+This document defines UIKit's animation tokens and related style rules.
+
+## Tokens (CSS Variables)
+
+Animation effects are defined using the `--transition-*` prefix.
+
+- `--transition-surface-duration`: Default surface transition duration (420ms)
+- `--transition-surface-ease`: Default surface transition timing function (cubic-bezier)
+- `--transition-background`: Background color transition
+- `--transition-color`: Text color transition
+- `--transition-font-size`: Font size transition
+- `--transition-outline`: Outline transition
+- `--transition-opacity`: Opacity transition
+- `--transition-border`: Border transition
+- `--transition-transform`: Transform transition
+- `--transition-shadow`: Shadow transition
+- `--transition-radius`: Border-radius transition
+- `--transition-filter`: Filter (blur, etc.) transition
+- `--transition-icon`: Combined icon transition (fill, stroke, color)
+- `--transition-surface`: Combined surface transition (border, background, outline)
+- `--transition-default`: General shape/transform combined transition
+- `--transition-fade`: Simple opacity fade
+- `--transition-pressable`: Click effect transition for pressable components such as buttons
+
+## Scaling
+
+- `--s-shallow`: Slight shrink effect `scaleX(.99) scaleY(.99)`
+- `--s`: Default click shrink effect `scaleX(.96) scaleY(.96)`
+
+## Usage
+
+AI/human developers inject the CSS variables directly into components that require animation effects.
+
+```css
+.button {
+  transition: var(--transition-pressable);
+}
+.button:active {
+  transform: var(--s);
+}
+```

package/.agents/references/Styles/Color.md

@@ -0,0 +1,45 @@
+# Color
+
+This document defines UIKit's color system and tokens.
+
+## Tokens (CSS Variables)
+
+### 1. Primitive Colors (Level 1 ~ Level 6)
+
+The base color palette is provided from level 1 (bright/light) to level 6 (dark/saturated).
+
+- Pink, Red, Brown, Orange, Yellow, Green, Mint, Cyan, Blue, Indigo, Purple, Magenta
+- Base Light (white/gray-tone family)
+- Base Dark (black/dark-gray family)
+- e.g. `--color-blue-4`, `--color-red-5`
+
+### 2. Semantic/Base Colors (Light/Dark mode support)
+
+- `--color-text-base`: Default text color
+- `--color-icon-base`: Default icon color
+- `--color-border-base`: Default border color
+- `--color-background-base`: Default background color (system/modal background, etc.)
+
+Depending on the mode, the `--color-base-*` family is swapped:
+
+- `light`: `--color-base-1` is the light tone, `--color-base-reversed-1` is the dark tone
+- `dark`: `--color-base-1` is the dark tone, `--color-base-reversed-1` is the light tone
+
+## Usage
+
+AI/human developers must avoid hardcoding color values (hex, rgb) and always use color tokens when specifying colors.
+
+```css
+/* Good */
+.card {
+  background-color: var(--color-background-base);
+  color: var(--color-text-base);
+  border: 1px solid var(--color-blue-4);
+}
+
+/* Bad - Do not hardcode colors */
+.card {
+  background-color: #ffffff;
+  color: #333333;
+}
+```

package/.agents/references/Styles/Font.md

@@ -0,0 +1,37 @@
+# Font
+
+This document defines UIKit's font configuration and system.
+
+## External Font Imports
+
+- Asta Sans
+- Min Icon
+- Tossface (Emoji)
+- JetBrains Mono
+- Source Han Serif KR
+- Pretendard
+
+## Tokens (CSS Variables)
+
+- `--font-size`: Base font size (`10px`) => 1rem = 10px baseline
+- `--font-emoji`: Emoji font stack
+- `--font-monospace`: Monospace font stack
+- `--font-icon`: Icon font stack
+- `--font-sans-serif`: Default sans-serif font stack (Pretendard, etc.)
+- `--font-serif`: Default serif font stack
+
+## Utility Classes
+
+- `.FontSerif`: Force apply serif font
+- `.FontCode`, `code`: Force apply monospace (Mono) font
+
+## Usage
+
+Use font family variables when specifying the font of a component or element in CSS.
+
+```css
+.custom-code-block {
+  font-family: var(--font-monospace);
+  font-size: 1.4rem;
+}
+```

package/.agents/references/Styles/Icon.md

@@ -0,0 +1,43 @@
+# Icon
+
+This document defines the icon font (min-icon based) and related weight adjustment classes.
+
+## Icon Font Configuration
+
+By default it is rendered using the `i` tag, with the `--font-icon` font stack and `font-variation-settings` applied. When the `.iFill` class is specified, the font setting (ss09) is turned on and the icon is converted to a filled (Solid) icon.
+
+## Weight
+
+Supports classes for fine-grained control of icon weight. Controls the CSS variable `--uikit-icon-font-weight`.
+
+- `.iThin` (100)
+- `.iExtraLight` (200)
+- `.iLight` (300)
+- `.iRegular` (400)
+- `.iMedium` (500)
+- `.iSemiBold` (600)
+- `.iBold` (700)
+- `.iExtraBold` (800)
+- `.iBlack` (900)
+
+## Icon Classes
+
+Approximately several hundred icon classes are defined. Class names follow the `.i{IconName}` rule. Examples:
+
+- `.iCircle`, `.iSquare`
+- `.iClose`, `.iCheck`, `.iAdd`, `.iRemove`
+- `.iInfo`, `.iWarning`, `.iQuestion`
+- `.iMenu`, `.iMoreHoriz`, `.iMoreVert`
+- Plus many arrows (Arrow), devices (Device), UI elements, etc.
+
+## Usage
+
+Render on screen by using a dedicated component or by combining classes on HTML tags (mainly `<i>` or `<span class="icon">`).
+
+```html
+<!-- Thin outlined close icon -->
+<i class="iClose iLight"></i>
+
+<!-- Bold filled warning icon -->
+<i class="iWarning iFill iBold"></i>
+```

package/.agents/references/Styles/Importer.md

@@ -0,0 +1,19 @@
+# Importer
+
+The `_importer.scss` file is the entry point that imports and bundles all SCSS modules within the Styles package.
+
+## Loaded Module List
+
+1. `animation`
+2. `color`
+3. `font`
+4. `icon`
+5. `system`
+6. `textstyle`
+7. `theme`
+8. `viewport`
+9. `viewport-global`
+
+## Usage
+
+This file is used as the package distribution and compiler entry point. When adding styles, write them in individual files and add them to the Importer if necessary. During normal component development there is almost no need to modify this file directly.

package/.agents/references/Styles/System.md

@@ -0,0 +1,27 @@
+# System
+
+This document defines UIKit's global styles and base initialization (CSS Reset) rules.
+
+## Core Rules
+
+1. **Box Sizing & Font**
+   - All elements (`*`, `::before`, `::after`) have `box-sizing: border-box`.
+   - The default font `var(--font-sans-serif)` is applied.
+   - `word-break: keep-all` prevents Korean word breaking.
+
+2. **Root (html, body)**
+   - `html`: `font-size: var(--font-size)` is applied so scaling is based on 1rem = 10px.
+   - `html`: Default text color (`var(--color-text-base)`) and background color (`var(--color-background-base)`) are set.
+   - `body`: Uses a centered flex-col layout by default, with margin/padding reset.
+
+3. **Form Elements & Interactive Elements (a, button, input, etc.)**
+   - Background, border, margin, padding, and outline are reset.
+   - `a`, `button` have `cursor: pointer`.
+   - `input::placeholder` opacity is set to 0.4.
+
+4. **Disabled State**
+   - `*:disabled`, `*[disabled]`, `.disabled` elements have `cursor: not-allowed` and `opacity: .4`, and events are blocked (`pointer-events: none`).
+
+## Usage
+
+Loaded at the top of the app without any explicit call to build the global environment. When developing components, be aware of these reset rules (e.g., buttons have no default background/border) and override styles accordingly.

package/.agents/references/Styles/Textstyle.md

@@ -0,0 +1,45 @@
+# Textstyle
+
+This document defines the typography hierarchy and text style utility classes.
+
+## Tokens (CSS Variables)
+
+Font size and line-height are managed as tokens.
+
+- `LargeTitle`: 3.8rem / 4.1rem
+- `Title1`: 2.6rem / 3.3rem
+- `Title2`: 2.2rem / 2.8rem
+- `Title3`: 2.rem / 2.5rem
+- `Headline`: 1.8rem / 2.2rem
+- `Body`: 1.8rem / 2.2rem
+- `Callout`: 1.7rem / 2.1rem
+- `Subheadline`: 1.6rem / 2.0rem
+- `Footnote`: 1.3rem / 1.8rem
+- `Caption1`: 1.2rem / 1.7rem
+- `Caption2`: 1.1rem / 1.3rem
+
+## Utility Classes
+
+Utility classes that can be used immediately on HTML tags or classes per the design system. Letter-spacing and font-weight are optimized for the font size.
+
+- `.LargeTitle`
+- `.Title1`, `h1`
+- `.Title2`, `h2`
+- `.Title3`, `h3`
+- `.Headline`, `h4`
+- `.Body`, `p`
+- `.Callout`, `blockquote`
+- `.Subheadline`, `h5`
+- `.Footnote`, `h6`
+- `.Caption1`, `small`
+- `.Caption2`
+
+## Usage
+
+Use the provided classes instead of inline styles to specify text component styles.
+
+```html
+<h1 class="Title1">Page Title</h1>
+<p class="Body">This is body text.</p>
+<span class="Caption1">Additional description</span>
+```

package/.agents/references/Styles/Theme.md

@@ -0,0 +1,51 @@
+# Theme
+
+This document defines the theme utility used throughout the app. It includes comprehensive tokens and mixins for background colors, borders, shadows, rounding (Radius), and blur effects.
+
+## Tokens (CSS Variables)
+
+- `--radius-*`: Corner rounding (circle, system-extra-light, system-light, system, system-bold, system-extra-bold, system-heavy)
+- `--shadow-base-*`: Shadow tokens (levels 1~3). In dark mode, the shadow tone changes to a brighter variant.
+
+## Utility Classes
+
+### 1. ThemeBg (Background & Interactive)
+
+Specifies the color system's level 1~6 colors as background. Classes with the TP (transparency) suffix apply a transparent background.
+
+- `.ThemeBg-{Color}{Level}` (e.g., `.ThemeBg-Blue4`)
+- `.ThemeBg-{Color}{Level}TP{Alpha}` (e.g., `.ThemeBg-BaseDark1TP3`)
+
+> Interactive state (when combined with the `ThemeInteractive` class): Bright colors with `Level` 4 or below dynamically level-up on hover/active to provide click feedback.
+
+### 2. ThemeColor (Foreground)
+
+- `.ThemeColor-{Color}{Level}`: Overrides the element's `color` and `stroke` with the specified color. (e.g., `.ThemeColor-Red5`)
+
+### 3. ThemeBorder (Border)
+
+Supports thickness (Light, Regular, Bold) and direction (1: all, 2: left-right, 3: bottom, 4: left).
+
+- `.ThemeBorder-{Color}{Level}-{Width}`
+- `.ThemeBorder{Direction}-{Color}{Level}-{Width}` (e.g., `.ThemeBorder3-Base4-Regular`)
+- Passing `None` makes it transparent.
+
+### 4. Interactive & Shadow & Blur
+
+- `.ThemeInteractive`: When used alone (without a background color), a semi-transparent black/white mask is applied on hover/active to give click feedback.
+- `.ThemeShadow-{1~3}`: Applies shadow by level. `.ThemeShadow-None` is supported.
+- `.BackgroundBlur-{Level}`: `backdrop-filter: blur` effect.
+
+
+## Usage
+
+Mix tokens and classes to compose the base form of UI components such as buttons, cards, and modals.
+
+```html
+<div
+  class="ThemeBg-Base1 ThemeShadow-2 ThemeBorder-Base3-Light"
+  style="border-radius: var(--radius-system);"
+>
+  <span class="ThemeColor-Blue4">Text</span>
+</div>
+```

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

@@ -0,0 +1,42 @@
+# Viewport Global
+
+This document defines global utility classes based on viewport (responsive resolution). Generated based on the mixins in `_viewport.scss`.
+
+## Breakpoints
+
+- `w1`: ~ 319.98px
+- `w2`: 320px ~ 409.98px
+- `w3`: 410px ~ 767.98px
+- `w4`: 768px ~ 1279.98px
+
+## Utility Classes
+
+Prefixed with `wX` to control responsive behavior. (e.g., `.w1-h`, `--w1-h` supported)
+
+### 1. Single Interval Control
+
+- `.{key}-h`: `display: none` at or below the interval
+- `.{key}-s`: `display: none` above the interval
+- `.{key}-scrollX`: Enables horizontal scroll (`overflow-x: auto`) at or below the interval
+- `.{key}-col`: Changes to `flex-direction: column` at or below the interval
+
+### 2. Composite Interval Control (Between)
+
+Combines two breakpoints to create an interval. (e.g., `w2w3`)
+
+- `.{start}{end}-h`: `display: none` between start ~ end
+- `.{start}{end}-s`: `display: none` outside the specified interval (i.e., visible only within that interval)
+
+## Usage
+
+When writing responsive layouts, control visibility through HTML classes rather than writing new CSS media queries.
+
+```html
+<!-- Enable horizontal scroll at w3 size (767px) or below -->
+<div class="w3-scrollX">
+  <!-- item list -->
+</div>
+
+<!-- Hidden on mobile (w2 or below) -->
+<div class="w2-h">Text visible only on PC</div>
+```