opencloud/.agents/skills/naive-ui-design-layout/SKILL.md

name, description, metadata

name	description	metadata
naive-ui-design-layout	Layout system for Naive UI including Grid, Flex, Space, and Layout components. Invoke when user needs to create responsive layouts, grid systems, or understand layout components.	author version jiaiyan 1.0.0

Layout System

Naive UI provides a comprehensive layout system including CSS Grid-based layout, Flexbox, Space, and Layout components for building responsive page structures.

When to Use

• Creating responsive grid layouts
• Building page structures with header, sidebar, content, and footer
• Implementing flexible layouts with Flexbox
• Adding consistent spacing between elements

---

Grid System (n-grid)

Naive UI uses a CSS Grid-based layout system with 24 columns by default.

Basic Concepts

• 24-column system: Default is 24 columns, configurable
• CSS Grid: Uses native CSS Grid for layout
• Responsive: Supports responsive breakpoints
• Flexible: Items can span multiple columns

Basic Grid

<template>
  <n-grid :cols="24">
    <n-gi :span="24">Full width</n-gi>
  </n-grid>
  
  <n-grid :cols="24">
    <n-gi :span="12">Half width</n-gi>
    <n-gi :span="12">Half width</n-gi>
  </n-grid>
  
  <n-grid :cols="24">
    <n-gi :span="8">One third</n-gi>
    <n-gi :span="8">One third</n-gi>
    <n-gi :span="8">One third</n-gi>
  </n-grid>
</template>

Grid with Gaps

<template>
  <n-grid :cols="4" :x-gap="12" :y-gap="8">
    <n-gi v-for="i in 8" :key="i">
      <div class="item">{{ i }}</div>
    </n-gi>
  </n-grid>
</template>

Responsive Grid

<template>
  <n-grid :cols="4" responsive="screen">
    <n-gi :span="4" :xs="24" :sm="12" :md="8" :lg="6" :xl="4">
      Responsive item
    </n-gi>
  </n-grid>
</template>

Grid Item Offset

<template>
  <n-grid :cols="24">
    <n-gi :span="6" :offset="6">Offset by 6</n-gi>
  </n-grid>
</template>

Grid Props

Name	Description	Type	Default
cols	Number of columns	number | string	24
x-gap	Horizontal gap	number | string	0
y-gap	Vertical gap	number | string	0
responsive	Responsive mode	'self' | 'screen'	'self'
collapsed	Collapsed state	boolean	false
collapsedRows	Rows when collapsed	number	1

Grid Item Props

Name	Description	Type	Default
span	Number of columns to span	number | string	1
offset	Number of columns to offset	number	0
suffix	Whether it's a suffix item	boolean	false

---

Flex Component (n-flex)

A flexible flexbox layout component.

Basic Flex

<template>
  <n-flex>
    <div>Item 1</div>
    <div>Item 2</div>
    <div>Item 3</div>
  </n-flex>
</template>

Flex with Justify

<template>
  <n-flex justify="center">
    <div>Centered</div>
  </n-flex>
  
  <n-flex justify="space-between">
    <div>Left</div>
    <div>Right</div>
  </n-flex>
</template>

Flex Vertical

<template>
  <n-flex vertical>
    <div>Item 1</div>
    <div>Item 2</div>
  </n-flex>
</template>

Flex Props

Name	Description	Type	Default
justify	Horizontal alignment	'start' | 'end' | 'center' | 'space-around' | 'space-between' | 'space-evenly'	'start'
align	Vertical alignment	'start' | 'end' | 'center' | 'stretch' | 'baseline'	—
vertical	Vertical direction	boolean	false
reverse	Reverse direction	boolean	false
wrap	Enable wrapping	boolean	true
inline	Inline flex	boolean	false
size	Gap size	'small' | 'medium' | 'large' | number | [number, number]	'medium'

---

Space Component (n-space)

Add consistent spacing between elements.

Basic Space

<template>
  <n-space>
    <n-button>Button 1</n-button>
    <n-button>Button 2</n-button>
    <n-button>Button 3</n-button>
  </n-space>
</template>

Space Sizes

<template>
  <n-space size="small">Small gap</n-space>
  <n-space size="medium">Medium gap</n-space>
  <n-space size="large">Large gap</n-space>
  <n-space :size="24">Custom 24px gap</n-space>
</template>

Vertical Space

<template>
  <n-space vertical>
    <n-button>Top</n-button>
    <n-button>Bottom</n-button>
  </n-space>
</template>

Space Props

Name	Description	Type	Default
size	Gap size	'small' | 'medium' | 'large' | number | [number, number]	'small'
vertical	Vertical direction	boolean	false
wrap	Enable wrapping	boolean	true
inline	Inline mode	boolean	false

---

Layout Components (n-layout)

Build complete page layouts with header, sidebar, content, and footer.

Basic Layout

<template>
  <n-layout>
    <n-layout-header>Header</n-layout-header>
    <n-layout-content>Content</n-layout-content>
    <n-layout-footer>Footer</n-layout-footer>
  </n-layout>
</template>

Layout with Sidebar

<template>
  <n-layout has-sider>
    <n-layout-sider>Sidebar</n-layout-sider>
    <n-layout>
      <n-layout-header>Header</n-layout-header>
      <n-layout-content>Content</n-layout-content>
      <n-layout-footer>Footer</n-layout-footer>
    </n-layout>
  </n-layout>
</template>

Collapsible Sidebar

<script setup>
import { ref } from 'vue'
const collapsed = ref(false)
</script>

<template>
  <n-layout has-sider>
    <n-layout-sider
      bordered
      collapse-mode="width"
      :collapsed-width="64"
      :width="240"
      :collapsed="collapsed"
      show-trigger
      @collapse="collapsed = true"
      @expand="collapsed = false"
    >
      Sidebar
    </n-layout-sider>
    <n-layout-content>Content</n-layout-content>
  </n-layout>
</template>

Layout Props

Name	Description	Type	Default
embedded	Embedded mode (no background)	boolean	false
position	Position mode	'static' | 'absolute'	'static'
native-scrollbar	Use native scrollbar	boolean	true
has-sider	Has sidebar	boolean	false
sider-placement	Sidebar placement	'left' | 'right'	'left'

Layout Sider Props

Name	Description	Type	Default
bordered	Show border	boolean	false
collapsed	Collapsed state	boolean	false
collapse-mode	Collapse mode	'width' | 'transform'	'transform'
collapsed-width	Width when collapsed	number	48
width	Sidebar width	number	272
show-trigger	Show collapse trigger	boolean	false

---

Responsive Breakpoints

Naive UI uses default breakpoints for responsive design:

Breakpoint	Screen Width
xs	< 640px
s	≥ 640px
m	≥ 1024px
l	≥ 1280px
xl	≥ 1536px
xxl	≥ 1920px

Using Breakpoints

<template>
  <n-grid :cols="4" responsive="screen">
    <n-gi :span="1" :xs="4" :s="2" :m="1">
      Responsive grid item
    </n-gi>
  </n-grid>
</template>

---

Best Practices

1. Use Grid for 2D layouts: Use n-grid when you need both rows and columns
2. Use Flex for 1D layouts: Use n-flex for single-row or single-column layouts
3. Use Space for simple gaps: Use n-space for consistent spacing between elements
4. Layout composition: Combine Layout components for full-page structures
5. Responsive design: Use responsive props for mobile-first design
6. Collapsed sidebar: Use collapse-mode="width" for better animation performance

---

Related Resources

Resource	Description
Grid Component	Grid documentation
Flex Component	Flex documentation
Space Component	Space documentation
Layout Component	Layout documentation