diff --git a/apps/landing/src/app/(detail)/docs/LeftMenu.tsx b/apps/landing/src/app/(detail)/docs/LeftMenu.tsx index d3485904..f1e50a92 100644 --- a/apps/landing/src/app/(detail)/docs/LeftMenu.tsx +++ b/apps/landing/src/app/(detail)/docs/LeftMenu.tsx @@ -18,11 +18,37 @@ export function LeftMenu() { to: '/docs/core-concepts/style-storage', children: 'Style Storage', }, + { + to: '/docs/core-concepts/type-inference-system', + children: 'Type Inference System', + }, + { + to: '/docs/core-concepts/optimize-css', + children: 'Optimize CSS', + }, + { + to: '/docs/core-concepts/nm-base', + children: 'N/M Base', + }, ]} > Core Concepts Features + + Figma and Theme Integration + +
+ ```tsx // Input +
+ + + +
+ ``` +
+
+ ```tsx // Output (N/M base class names) +
+ {/* bg: red */} + {/* bg: blue */} + {/* color: white */} +
+ ``` +
+ + +### **Responsive Class Names** + +
+
+ ```tsx // Input + + ``` +
+
+ ```tsx // Output + + {/* w: 100px, w: 200px, w: 300px */} + ``` +
+
+ +### **Pseudo-selector Class Names** + +
+
+ ```tsx + + ``` +
+
+ ```tsx + + {/* .g:hover { background: red; } */} + ``` +
+
+ +### **File-specific Class Names** + +
+
+ ```tsx +
+ + +
+ ``` +
+
+ ```tsx +
+ {/* file1.tsx */} + {/* file2.tsx */} +
+ ``` +
+
+ +## Ad-blocker Compatibility + +### **Why "ad" is Problematic** + +Ad-blockers recognize and block class names containing "ad" patterns as advertisements: + +- **Ad-blocker filters**: Classify elements containing "ad" strings as advertisements +- **CSS blocking**: Styles are not applied, causing UI to break +- **Poor user experience**: Unintended style blocking causes layout issues + +### **Our Solution** + +Devup UI prevents ad-blocker conflicts through the following methods: + +- **Pattern avoidance**: Automatically converts class names ending with "ad" to "a-d" +- **Safe character usage**: Uses only `a-z`, `-`, `_` to avoid blocking patterns +- **No numbers**: Ensures class names don't start with digits to comply with CSS constraints + +## Advantages + +- **Compact class names**: First 26 styles generate single characters like `a`, `b`, `c` +- **Build consistency**: Always generates the same class name for identical input +- **Cache optimization**: Consistent class names improve browser cache efficiency +- **Collision prevention**: Each style has a unique signature to prevent class name collisions +- **Ad-blocker compatibility**: Automatically converts "ad" patterns to "a-d" to prevent blocking +- **CSS constraint compliance**: Class names don't start with digits to comply with CSS rules diff --git a/apps/landing/src/app/(detail)/docs/core-concepts/optimize-css/page.mdx b/apps/landing/src/app/(detail)/docs/core-concepts/optimize-css/page.mdx new file mode 100644 index 00000000..736e94c3 --- /dev/null +++ b/apps/landing/src/app/(detail)/docs/core-concepts/optimize-css/page.mdx @@ -0,0 +1,205 @@ +export const metadata = { + title: 'Optimize CSS', + alternates: { + canonical: '/docs/core-concepts/optimize-css', + }, +} + +# Optimize CSS + +Devup UI automatically optimizes CSS output through micro-unit optimization, duplicate removal, and intelligent value conversion to minimize bundle size and improve performance. This document explains the various CSS optimization techniques used by Devup UI, including micro-unit optimization, color optimization, and global CSS handling. + +## Micro-unit Optimization + +### **Value Optimization** + +Devup UI optimizes CSS values by: + +- **Removing unnecessary zeros**: `0px` becomes `0` +- **Shortening decimals**: `0.5000` becomes `0.5` +- **Optimizing units**: `0px` becomes `0` when appropriate +- **Converting to alternative units**: `0px` is converted to `0%` in CSS functions where unit-less zero is not allowed +- **Removing redundant spaces**: `margin: 0 0 0 0` becomes `margin:0` + +``` +// Before optimization + + +// After optimization + +``` + +### **Aspect Ratio Optimization** + +Aspect ratios are simplified to their smallest equivalent ratio using the greatest common divisor (GCD). +For example, 500/100 becomes 5/1, while 16/9 remains unchanged since GCD(16, 9) = 1. + +```tsx +// Before: aspect-ratio: 500/100 + + +// After: aspect-ratio: 5/1 (optimized) +// The system calculates GCD(500, 100) = 100, simplifying the ratio to 5/1 +``` + +## Color Optimization + +### **RGB/RGBA to Hex Conversion** + +All RGB and RGBA color values are normalized and converted into compact hexadecimal form. + +``` +// Input + + + +// Output + // #ff0000 shortened to #f00 + // #ff000080 shortened to #f000 +``` + +### **Hex Shortening** + +Hex shortening converts long hex codes into their shortest possible form. +Six- or eight-digit values are reduced to three or four digits when safely equivalent. + +```tsx +// 6-digit hex to 3-digit +// #ffffff → #fff +// #000000 → #000 +// #ff0000 → #f00 + +// 8-digit hex to 4-digit (when alpha is FF) +// #ffffffff → #ffff +// #000000ff → #000f +``` + +### **Alpha Channel Optimization** + +Alpha channel optimization removes unnecessary opacity information. +Fully opaque colors (FF) are shortened, while partial transparency values are preserved for accuracy. + +```tsx +// Full opacity is removed and shortened to 3-digit hex +// #ff0000ff → #f00 + +// Partial opacity is preserved and shortened to 4-digit hex +// #ff000080 → #f000 +``` + +## Global CSS Optimization + +### **CSS Block Optimization** + +Global CSS blocks are optimized by: + +- **Minifying whitespace**: Multiple spaces become single spaces +- **Removing semicolons**: Last property in a block doesn't need semicolon + +```css +/* Before optimization */ +div { + /* comment */ + background-color: red; + /* color: blue; */ +} + +/* After optimization */ +div { + background-color: red; +} +``` + +### **Keyframes Optimization** + +Keyframes are optimized for minimal output: + +```tsx +// Input +const fadeIn = keyframes({ + from: { opacity: 0 }, + to: { opacity: 1 }, +}) + +// Output (optimized) +// @keyframes k-fadeIn{from{opacity:0}to{opacity:1}} +``` + +### **Font Face Optimization** + +Font faces are automatically added and optimized: + +```tsx +// Input + + +// Output (optimized) +// @font-face{font-family:Inter;src:url(./fonts/Inter.woff2)} +``` + +## Value Conversion + +### **Unit Conversion** + +Values are converted to their most appropriate units: +Numeric values are automatically interpreted as pixel units, while string-based values with explicit units (e.g., rem, %) are preserved for accurate rendering. + +``` +// Numbers without units are treated as pixels (multiplied by 4) + // width: 64px + +// Strings with units are preserved + // width: 16rem + // width: 100% +``` + +### **Zero Value Optimization** + +Zero values are optimized: + +``` +// Before + + +// After + +``` + +## Duplicate Removal + +### **Style Deduplication** + +Identical style rules across multiple components are automatically merged into a single CSS rule, reducing redundancy and overall bundle size. + +```tsx +// Multiple components with same styles +
+ + + +
+ +// Output: Only one CSS rule generated +// .red-white{background:red;color:white} +``` + +### **Advantages** + +Devup UI offers complete flexibility in how you implement and optimize styles — while maintaining measurable performance gains. + +- **Flexible syntax support** – Use CSS utility objects, template literals, or prop-based expressions seamlessly in one system +- **Smaller bundle size** – Reduced CSS output through color, value, and duplicate optimization +- **Faster parsing** – Lightweight CSS loads and parses quickly in browsers +- **Better caching** – Compact, consistent values improve cache efficiency +- **Lower memory usage** – Reduced CSS footprint minimizes runtime memory consumption + +This unified approach ensures both **maximum developer freedom** and **optimized performance**, +allowing teams to write CSS their way without compromising efficiency. diff --git a/apps/landing/src/app/(detail)/docs/core-concepts/type-inference-system/page.mdx b/apps/landing/src/app/(detail)/docs/core-concepts/type-inference-system/page.mdx new file mode 100644 index 00000000..333a4fea --- /dev/null +++ b/apps/landing/src/app/(detail)/docs/core-concepts/type-inference-system/page.mdx @@ -0,0 +1,39 @@ +export const metadata = { + title: 'Type Inference System', + alternates: { + canonical: '/docs/core-concepts/type-inference-system', + }, +} + +# Type Inference System + +Devup UI automatically infers TypeScript types for CSS properties, ensuring type safety and a smooth developer experience — no manual definitions required. +Unlike traditional CSS-in-JS libraries, Devup UI **derives types directly from CSS standards**. + +## How It Works + +Devup UI uses the **csstype** package to automatically generate types for CSS properties. Instead of manually defining types, Devup UI reads the standard CSS definitions from csstype and uses them directly. + +### 1. Reading CSS Standards + +Devup UI reads all CSS property definitions from the **csstype** package, which contains the official CSS standards. This includes both regular properties (like `width`, `color`) and shorthand properties (like `margin`, `padding`). + +### 2. Auto-Converting Selectors + +When you use CSS states like `:hover` or `:focus`, Devup UI automatically converts them into props you can use. For example, `:hover` becomes `_hover` so you can write ``. + +When `csstype` is updated with new CSS standards, Devup UI automatically gets these updates without needing a library update. + +### 3. Catching Mistakes Early + +TypeScript checks your CSS properties while you're coding. If you try to use an invalid property or value, you'll get an error right away instead of discovering it later. + +## Advantages + +Devup UI's type inference system provides several key benefits: + +- **Automatic updates** – New CSS properties are supported immediately when the csstype package is updated. Simply update the package without requiring devup-ui library updates. +- **Type safety** – All properties and values are strictly typed based on CSS standards, preventing invalid or misspelled declarations at compile time. +- **Standards compliance** – Types are always aligned with official CSS specifications, ensuring accuracy and consistency across all CSS standards. + +This type inference system is automatic, reliable, and future-ready, allowing developers to focus on design and logic rather than manual type management. diff --git a/apps/landing/src/app/(detail)/docs/figma-and-theme-integration/devup-figma-plugin/page.mdx b/apps/landing/src/app/(detail)/docs/figma-and-theme-integration/devup-figma-plugin/page.mdx new file mode 100644 index 00000000..3a33d503 --- /dev/null +++ b/apps/landing/src/app/(detail)/docs/figma-and-theme-integration/devup-figma-plugin/page.mdx @@ -0,0 +1,34 @@ +export const metadata = { + title: 'Devup Figma Plugin', + alternates: { + canonical: '/docs/figma-and-theme-integration/devup-figma-plugin', + }, +} + +# Devup Figma Plugin + +Devup UI provides a powerful Figma plugin that enables seamless integration between design and development workflows. The plugin converts Figma layers into Devup UI code snippets and exports design tokens. + +### **From Figma Community** + +1. Open Figma +2. Go to **Plugins** → **Browse all plugins** +3. Search for "Devup UI" +4. Click **Open in Figma** on the Devup UI plugin or go to directly [Figma Community page](https://www.figma.com/community/plugin/1412341601954480694). + +## Features + +### **Layer to Component Conversion** + +Convert Figma layers into Devup UI components. + +```tsx +// Generated from Figma layer + + Button Text + +``` + +### **Design Token Export** + +Export design tokens from Figma to your `devup.json`. diff --git a/apps/landing/src/app/(detail)/docs/figma-and-theme-integration/devup-json/page.mdx b/apps/landing/src/app/(detail)/docs/figma-and-theme-integration/devup-json/page.mdx new file mode 100644 index 00000000..92038e9f --- /dev/null +++ b/apps/landing/src/app/(detail)/docs/figma-and-theme-integration/devup-json/page.mdx @@ -0,0 +1,188 @@ +export const metadata = { + title: 'devup.json Configuration', + alternates: { + canonical: '/docs/figma-and-theme-integration/devup-json', + }, +} + +# devup.json Configuration + +The `devup.json` file is the central configuration file for Devup UI that allows you to define custom themes, colors, typography, and other design tokens. + +## Basic Structure + +```json +{ + "theme": { + "colors": { + "primary": "#5A44FF" + }, + "typography": { + "h1": { + "fontSize": "32px" + } + } + } +} +``` + +## Colors Configuration + +### **Basic Color Setup** + +Define colors for different themes. + +```json +{ + "theme": { + "colors": { + "light": { + "primary": "#5A44FF", + "secondary": "#85A5F2", + "text": "#2F2F2F", + "background": "#FFF" + }, + "dark": { + "primary": "#9086FF", + "secondary": "#2A4586", + "text": "#EDEDED", + "background": "#131313" + } + } + } +} +``` + +### **Semantic Color Naming** + +Use semantic names that describe purpose. + +```json +{ + "theme": { + "colors": { + "light": { + "primary": "#5A44FF", + "primaryHover": "#4D38AE", + "text": "#2F2F2F", + "textSecondary": "#787878", + "background": "#FFF", + "surface": "#F8F8F8", + "success": "#4CAF50", + "warning": "#FF9800", + "error": "#F44336" + } + } + } +} +``` + +### **Color Variants** + +Create color variants with opacity. + +```json +{ + "theme": { + "colors": { + "light": { + "primary": "#5A44FF", + "primary50": "#5A44FF80", + "primary20": "#5A44FF33", + "black50": "#00000080" + } + } + } +} +``` + +## Typography Configuration + +### **Typography Properties** + +Each typography definition can include. + +- **fontFamily**: Font family name +- **fontWeight**: Numeric weight (100-900) or string +- **fontSize**: Size with unit (`16px`, `1rem`) +- **lineHeight**: Numeric ratio or string with unit +- **letterSpacing**: Spacing with unit (`-0.03em`) + +### **Typography Configuration** + +Define typography styles using objects for static values or arrays for responsive breakpoints. + +#### **Static typography** + +```json +{ + "theme": { + "typography": { + "caption": { + "fontFamily": "Pretendard", + "fontWeight": 500, + "fontSize": "14px", + "lineHeight": 1.4 + } + } + } +} +``` + +#### **Responsive typography** + +Use arrays to define styles for each breakpoint. + +```json +{ + "theme": { + "typography": { + "heading": [ + { + "fontFamily": "Pretendard", + "fontWeight": 700, + "fontSize": "20px", + "lineHeight": 1.3 + }, + { + "fontFamily": "Pretendard", + "fontWeight": 700, + "fontSize": "28px", + "lineHeight": 1.3 + }, + { + "fontFamily": "Pretendard", + "fontWeight": 700, + "fontSize": "32px", + "lineHeight": 1.2 + } + ] + } + } +} +``` + +## Usage in Components + +### **Color Usage** + +Access colors using the `$` prefix. + +```tsx + + Content + +``` + +- To enable type autocompletion for theme values, add `"df/*.ts"` to the `include` array in your `tsconfig.json` file. + +### **Typography Usage** + +Apply typography styles using the `typography` prop. + +```tsx +<> + Heading 1 + Body text + +```