Lily Design System™

เริ่มต้นกับ Lily

เลือกเฟรมเวิร์ก โคลนโมโนรีโพ แล้วเปิดไลบรารี headless หรือแอปตัวอย่างของมัน จากนั้นเริ่มประกอบหน้าของคุณเอง ชอบเส้นทางที่มีคนนำทางไหม? เริ่มกับ บทเรียน.

ติดตั้ง

Lily อยู่ในโมโนรีโพ Git เดียว โดยมีไดเรกทอรีสำหรับไลบรารี headless แพ็กเกจตัวช่วย และแอปตัวอย่างของแต่ละเฟรมเวิร์ก วิธีลองที่เร็วที่สุดคือโคลนโมโนรีโพแล้วเปิดไลบรารี headless สำหรับสแตกของคุณ: 

git clone https://github.com/LilyDesignSystem/lily-design-system
cd lily-design-system/lily-design-system-react-headless
pnpm install

รูปแบบเดียวกันใช้ได้กับเฟรมเวิร์กอื่น:

  • @lilydesignsystem/html-headless — ไม่ต้องติดตั้ง ให้คัดลอกไฟล์ .html
  • @lilydesignsystem/svelte-headless — pnpm install
  • @lilydesignsystem/react-headless — pnpm install
  • @lilydesignsystem/vue-headless — pnpm install
  • @lilydesignsystem/angular-headless — pnpm install
  • @lilydesignsystem/nunjucks-headless — pnpm install
  • lily-design-system-blazor-headless — dotnet build

ไลบรารี headless ออกแบบมาให้โคลนหรือนำไปรวมไว้ในโปรเจกต์ — ถือซอร์สโค้ดเป็นแหล่งความจริงและคัดลอกสิ่งที่คุณต้องการ ตัวช่วยการตั้งค่า ยังมีให้ในรูปแพ็กเกจที่ติดตั้งได้พร้อมไปป์ไลน์บิลด์และเผยแพร่ (npm สำหรับเฟรมเวิร์ก JS, NuGet สำหรับ Blazor)

ใช้คอมโพเนนต์ headless

คอมโพเนนต์ headless มี HTML เชิงความหมาย ARIA และ props — แต่ไม่มี CSS นี่คือ Button ในแต่ละเฟรมเวิร์ก:

HTML

<button class="button" type="button" aria-label="Save">
  Save
</button>

Svelte

<script>
  import Button from "lily-design-system-svelte-headless/components/Button/Button.svelte";
</script>

<Button onclick={save}>Save</Button>

React

import Button from "lily-design-system-react-headless/components/Button";

<Button onClick={save}>Save</Button>

Vue

<script setup>
  import Button from "lily-design-system-vue-headless/components/Button.vue";
</script>

<Button @click="save">Save</Button>

Angular

import { Button } from "@lilydesignsystem/angular-headless";

@Component({
  imports: [Button],
  template: `<lily-button (click)="save()">Save</lily-button>`,
})

Blazor

<Button OnClick="Save">Save</Button>

Nunjucks

{% from "components/button/macro.njk" import button %}

{{ button({ text: "Save", type: "button" }) }}

ใช้ตัวอย่างที่มีสไตล์

แอปตัวอย่างมี CSS เส้นทาง และหน้าเดโมเต็มรูปแบบ วิธีทดลองที่เร็วที่สุดคือเริ่มแอปตัวอย่าง SvelteKit, Next, Nuxt, Analog หรือ Eleventy แล้วดูเดโมที่ /components. 

git clone https://github.com/LilyDesignSystem/lily-design-system
cd lily-design-system/lily-design-system-svelte-sveltekit-examples
pnpm install
pnpm run dev

จากนั้นเปิด http://localhost:5173 และเรียกดู /components.

สไตล์และโทเค็นการออกแบบ

แต่ละคอมโพเนนต์เรนเดอร์ด้วยคลาสแบบ kebab-case หนึ่งคลาสบนองค์ประกอบราก ตัวอย่างเช่น <Button> เรนเดอร์เป็น <button class="button"> จัดสไตล์ได้ตามต้องการ: 

.button {
  background: var(--my-primary);
  color: #fff;
  padding: 0.75rem 1.5rem;
  border-radius: 0.5rem;
}
.button:hover { background: var(--my-primary-hover); }

จานสีเริ่มต้นของ Lily (ใช้ในแอปตัวอย่าง) คือ:

  • หลัก: #2563eb
  • อันตราย: #dc2626
  • คำเตือน: #f59e0b
  • สำเร็จ: #16a34a
  • พื้นหลังหน้า: #f9fafb
  • พื้นหลังการ์ด: #ffffff

สิ่งเหล่านี้เป็นข้อเสนอแนะ ไม่ใช่ข้อบังคับ แทนที่ด้วยจานสีแบรนด์ของคุณเอง แล้ว Lily จะปรับตามอย่างยินดี

ธีมสำเร็จรูป

ไม่อยากเขียน CSS ตั้งแต่ต้นใช่ไหม Lily มาพร้อม ธีมอ้างอิงแบบอิสระ 57 ธีม ในไดเรกทอรี themes/ แต่ละธีมคือสไตล์ชีตเดียวที่มุ่งเป้าไปที่คลาสฮุกของ Lily — ลิงก์แล้วก็มีสไตล์ทันที: 

<link rel="stylesheet" href="/assets/themes/united-kingdom-government-digital-service.css" />

ชุดนี้ครอบคลุม:

  • ภาครัฐ — NHS England, NHS Scotland และ NHS Wales (แต่ละแห่งมีรุ่นสำหรับผู้ป่วยและผู้ปฏิบัติงาน) GOV.UK GDS และ U.S. Web Design System
  • ได้แรงบันดาลใจจากผู้ให้บริการ — Adobe Spectrum, Mozilla Protocol
  • อเนกประสงค์ — light, dark, nord, dracula, wireframe และอีกกว่าสามสิบธีม

ตัวเลือกของธีมใช้ :where(...) ดังนั้น CSS ของคุณเองจึงชนะเสมอในด้านความจำเพาะ จับคู่กับตัวช่วย theme-picker ด้านล่างเพื่อสลับขณะรันไทม์ หรือทำตาม บทเรียนการจัดธีม.

ตัวช่วยการตั้งค่า

แต่ละเฟรมเวิร์กมีตัวเลือกขนาดเล็กแปดตัว แต่ละตัวเป็นแพ็กเกจ lily-design-system-{framework}-{package} ของตัวเอง (และ picker-bar ที่ประกอบเข้าด้วยกัน) แต่ละตัวเป็นปุ่มไอคอนแบบ headless ที่เปิดป๊อปอัป — กล่องรายการ รายการลิงก์ ฟอร์มค้นหา หรือ (สำหรับ date-time-picker) กล่องโต้ตอบเลือกวันที่ — ไม่ใช่ <select> แบบเนทีฟ ปลอดภัยต่อ SSR และไม่มี CSS:

  • theme-picker — โหลดสไตล์ชีตของธีมขณะรันไทม์โดยสลับ <link> ที่จัดการอยู่ ตั้งค่า data-theme บนเอกสาร และเลือกเก็บถาวรลงใน localStorage.
  • locale-picker — ตั้งค่า lang และ dir (พร้อมการตรวจจับ RTL อัตโนมัติ) เพื่อให้ไลบรารี i18n ของคุณตามได้ ไม่แปลเอง
  • text-size-picker — ตั้งค่า data-text-size บนเอกสาร CSS ของคุณจับคู่แต่ละค่ากับขนาดฟอนต์
  • motion-picker — ตั้งค่า data-motion บนเอกสาร โดยเริ่มจากการตั้งค่าลดการเคลื่อนไหวของผู้เข้าชม CSS และสคริปต์ของคุณตัดสินใจว่าจะระงับอะไร
  • search-picker — ปุ่มไอคอนที่เปิดช่องค้นหา การส่งจะนำไปยังหน้าค้นหา ดูแลการกระทำ ไม่ใช่การตั้งค่า
  • link-picker — ไอคอนบ้านที่เปิดเมนูลิงก์หน้าที่แอปของคุณกำหนด (หน้าแรก เกี่ยวกับเรา ติดต่อเรา นโยบายความเป็นส่วนตัว …) ดูแลการกระทำ ไม่ใช่การตั้งค่า
  • share-picker — เปิดชีตแชร์แบบเนทีฟหรือรายการปลายทางที่ผู้ใช้ไลบรารีกำหนด พร้อมคัดลอก URL ดูแลการกระทำ ไม่ใช่การตั้งค่า: ไม่ใช้อะไร ไม่เก็บอะไร
  • date-time-picker — ช่องข้อความพร้อมกล่องโต้ตอบเลือกวันที่ตาม APG สำหรับวันที่ เวลา หรือทั้งสองอย่าง ดูแลค่าของฟอร์ม ไม่ใช่การตั้งค่า: สตริง ISO แปลงไปมากับ <input type="date">. 
git clone https://github.com/LilyDesignSystem/lily-design-system
cd lily-design-system/lily-design-system-svelte-theme-picker

แคตตาล็อก Svelte เป็นข้อมูลอ้างอิงหลัก พอร์ตของ React, Vue, Angular, HTML, Nunjucks, Web Components และ Blazor ตรงกับมันทุกข้อตกลง ดู บทเรียนตัวช่วย.

การเข้าถึง

คอมโพเนนต์มุ่งเป้าไปที่ WCAG 2.2 AAA โดยทำตามรูปแบบเหล่านี้:

  • องค์ประกอบ HTML เชิงความหมายแทน <div>s.
  • <label for="id"> ทั่วไป
  • aria-labelledby / aria-describedby สำหรับการอ้างอิงข้าม
  • aria-invalid + aria-errormessage สำหรับสถานะข้อผิดพลาด
  • role="alert" และ aria-live สำหรับเนื้อหาที่เปลี่ยนแปลง
  • aria-pressed, aria-expanded, aria-current สำหรับสถานะ
  • tabindex แบบ roving สำหรับกริด

ตัวบ่งชี้โฟกัสให้ผู้ใช้ไลบรารีเป็นผู้จัดหาโดยตั้งใจ — Lily ไม่วาดวงแหวนโฟกัสเริ่มต้นที่ขัดกับการออกแบบของคุณ แอปตัวอย่างรักษาเส้นฐาน axe-core ที่สะอาดตลอดเส้นทางทั้งหมด

การรองรับหลายภาษา

ทุกป้ายกำกับ ตัวยึดตำแหน่ง ข้อความข้อผิดพลาด และข้อความบนปุ่มเป็น prop ไม่มีสตริงที่เขียนตายตัว ใส่เฟรมเวิร์กแปลภาษาที่คุณชอบ — Paraglide, i18next, vue-i18n, react-intl, ไฟล์ .resx อะไรก็ได้

สำหรับวันที่ ตัวเลข และสกุลเงิน คอมโพเนนต์รับสตริงที่จัดรูปแบบไว้แล้ว: คุณจัดรูปแบบด้วย Intl.DateTimeFormat / Intl.NumberFormat / ไลบรารีที่คุณชอบ แล้วส่งผลลัพธ์เข้ามา

ตัวช่วย locale-picker แจ้งภาษาและพื้นที่ที่เลือกให้ไลบรารี i18n ของคุณโดยตั้งค่า lang และ dir บนรากของเอกสาร

การทดสอบ

แต่ละโครงการย่อยของเฟรมเวิร์กมาพร้อมการทดสอบของตัวเองโดยใช้สแตกที่เป็นธรรมเนียมของมัน:

  • HTML: WebDriverIO ที่รันเบราว์เซอร์จริง
  • Svelte: Vitest + @testing-library/svelte.
  • React: Vitest + @testing-library/react.
  • Vue: Vitest + @testing-library/vue.
  • Angular: Vitest + TestBed (ผ่านปลั๊กอิน Analog Vite)
  • Nunjucks: Vitest พร้อมตัวช่วยเรนเดอร์
  • Blazor: bUnit

การทดสอบใช้ เฉพาะ matcher ที่มากับ Vitest — ไม่ใช้ jest-dom matcher เลย ซึ่งทำให้ชุดทดสอบพกพาได้ แอปตัวอย่างเพิ่มชุดทดสอบ Playwright แบบ end-to-end เส้นฐานการเข้าถึง axe-core และการกวาดตรวจวิวพอร์ตแบบตอบสนอง

เอเจนต์ AI

ไซต์นี้เผยแพร่ llms.txt และ llms.json ที่รากของไซต์ — แผนที่ที่คัดสรรของหน้าสำคัญที่สุด สำหรับเครื่องมือใดก็ตามที่ทำตาม ข้อตกลง llms.txt.

โมโนรีโพหลักยังมาพร้อม Claude Skills: lily-design-system-skill สองรายการ: skill อเนกประสงค์ที่ครอบคลุมแนวคิด คำศัพท์ และรูปแบบการประกอบของ Lily สำหรับทุกคนที่สร้างด้วยระบบนี้ และ lily-design-system-maintainer-skill skill เชิงเทคนิคที่ครอบคลุมโครงสร้างไฟล์ที่จำเป็นและเครื่องมือของโมโนรีโพสำหรับทุกคนที่ทำงานกับมัน ทั้งสองอยู่ที่รากของ โมโนรีโพหลัก.

การแก้ปัญหา

คอมโพเนนต์แสดงผลแต่ดูไม่มีสไตล์

นั่นคือ headless ที่ทำงานตามที่ตั้งใจ — ไม่มี CSS มากับคอมโพเนนต์ เขียน CSS กับคลาส kebab-case ของคอมโพเนนต์ (แสดงอยู่ใน ทุกหน้าของแคตตาล็อก) หรือลิงก์หนึ่งใน 57 ธีมสำเร็จรูป.

CSS ของฉันดูเหมือนไม่มีผลเหนือธีม

ควรมีผล — ตัวเลือกของธีมถูกห่อด้วย :where(...) ซึ่งมีความจำเพาะเป็นศูนย์ หากกฎยังแพ้ ให้ตรวจสอบว่าสไตล์ชีตของคุณโหลดหลัง <link> ของธีม และตัวเลือกตรงกับคลาสฮุกของคอมโพเนนต์จริง ๆ

pnpm install ล้มเหลวด้วยข้อผิดพลาดเรื่อง peer หรือเวอร์ชัน

ใช้ pnpm ปัจจุบัน (v10+) และ Node 22+ แต่ละโครงการย่อยตรึงเวอร์ชันเฟรมเวิร์กไว้ใน package.json ของตัวเอง หากเครื่องมือส่วนกลางของคุณเก่ากว่านั้น pnpm env use --global lts คือวิธีแก้ที่เร็วที่สุด

โปรแกรมอ่านหน้าจออ่านชื่อของตัวควบคุมผิด

ตรวจสอบ prop label ที่จำเป็นของคอมโพเนนต์ — คอมโพเนนต์ที่ไม่มีข้อความให้เห็นต้องมี และ aria-label / aria-labelledby ที่ผู้ใช้ส่งผ่าน rest-props จะชนะการเชื่อมต่อในตัวโดยตั้งใจ แต่ละหน้าของแคตตาล็อกบันทึกข้อตกลง ARIA ของคอมโพเนนต์

ตัวช่วย theme-picker ไม่สลับสไตล์ชีต

ตรวจสอบว่า themesUrl ชี้ไปยังไดเรกทอรีที่เบราว์เซอร์ดึงได้ (ให้บริการไฟล์ใน themes/ เป็นแอสเซ็ตสแตติก) และ slug ของธีมใน prop themes ตรงกับชื่อไฟล์ ตัวช่วยสลับ href ของ <link data-lily-theme-picker> ที่จัดการอยู่หนึ่งตัว — ตรวจดูใน devtools เพื่อดู URL ที่ถูกร้องขอ

มีอย่างอื่นพัง

เปิด issue พร้อมขั้นตอนทำซ้ำแบบน้อยที่สุดที่ github.com/LilyDesignSystem/lily-design-system — หรือดู ชุมชนและการสนับสนุน.

การสมทบ

Lily ยังใหม่และยินดีรับความร่วมมือ การสมทบที่มีประโยชน์ที่สุดในตอนนี้คือ:

  • คอมโพเนนต์ใหม่ (โดยเฉพาะรูปแบบจากระบบการออกแบบที่มั่นคง)
  • ธีมใหม่ — แต่ละธีมคือสไตล์ชีตอิสระหนึ่งไฟล์ เป็น PR แรกที่ขอบเขตชัดเจน
  • การจัดสไตล์ตัวอย่างที่ดีขึ้น — แสดงให้เห็นว่าทำอะไรได้บ้าง
  • การแปลสตริงของแอปตัวอย่าง
  • รายงานข้อบกพร่องพร้อมขั้นตอนทำซ้ำแบบน้อยที่สุด
  • การตรวจสอบการเข้าถึงด้วยโปรแกรมอ่านหน้าจอและเทคโนโลยีช่วยเหลือ

เปิด issue และ PR ได้ที่ github.com/LilyDesignSystem/lily-design-system.

ชุมชนและการสนับสนุน

  • คำถามและรายงานข้อบกพร่อง — เปิด issue ที่ github.com/LilyDesignSystem/lily-design-system.
  • อีเมล — ผู้ดูแลอ่าน joel@joelparkerhenderson.com และยินดีรับความร่วมมือ คำแนะนำ และข้อเสนอแนะ
  • มิเรอร์ — Lily ยังถูกพุชไปยัง Codeberg และ GitLab เพื่อให้คุณมีส่วนร่วมจากฟอร์จที่คุณชอบ
  • ความประพฤติ — โครงการนี้ใช้หลักปฏิบัติมาตรฐาน โปรดมีน้ำใจและเชื่อในเจตนาดี

คำถามที่พบบ่อย

ทำไมจึงเป็น headless แทนที่จะมีสไตล์?

คอมโพเนนต์ที่มีสไตล์สำเร็จรูปสะดวก — จนกว่าจะไม่เข้ากับแบรนด์ของคุณ คอมโพเนนต์ headless ต้องทำงานมากขึ้นเล็กน้อยตอนแรกแต่ให้คุณควบคุมการออกแบบด้านภาพได้ทั้งหมด แอปตัวอย่างและ 57 ธีมแสดงวิธีจัดสไตล์ คุณจะใช้ตามนั้นหรือแทนที่ทั้งหมดก็ได้ ข้อโต้แย้งฉบับยาวอยู่ที่ ทำไมต้อง Lily.

ทำไมมีคอมโพเนนต์มากมายขนาดนี้?

Lily มุ่งครอบคลุมรูปแบบที่แอปส่วนใหญ่ต้องการโดยไม่บังคับให้คุณสร้างเองตั้งแต่ต้น — รวมถึงของเชิงลึกอย่างช่องป้อนตัวระบุระดับชาติและ scrollytelling แบบบรรณาธิการ แคตตาล็อกนำมาจากระบบการออกแบบที่มั่นคงหลายสิบแห่งรวมกับงานดั้งเดิม — ดู เกี่ยวกับ.

ใช้ Lily กับ Tailwind ได้ไหม?

ได้ แต่ละคอมโพเนนต์เปิดเผยคลาสรากแบบ kebab-case หนึ่งคลาส พร้อม className / class ที่ผู้ใช้กำหนด วางยูทิลิตีของ Tailwind ทับได้ตามใจ

ใช้ Lily กับเฟรมเวิร์ก CSS เชิงความหมายอย่าง DaisyUI ได้ไหม?

ได้ ชื่อคลาสแบบ kebab-case บนองค์ประกอบรากทำงานเป็นฮุก CSS เชิงความหมาย จับคู่ Lily กับเฟรมเวิร์กเชิงความหมาย แล้วคุณจะได้คอมโพเนนต์ที่มีสไตล์สำเร็จรูปซึ่งยังเคารพ ARIA และ i18n

มีแพ็กเกจ npm ไหม?

ตัวช่วยการตั้งค่า มีให้ในรูปแพ็กเกจพร้อมไปป์ไลน์เผยแพร่ npm/NuGet ไลบรารีคอมโพเนนต์ headless ออกแบบมาให้โคลนหรือนำไปรวมไว้ในโปรเจกต์ — ซอร์สโค้ดคือสิ่งที่ส่งมอบ คุณจึงอ่าน ตัดแต่ง และเป็นเจ้าของสิ่งที่คุณส่งออกได้อย่างแท้จริง การเผยแพร่ไลบรารี headless ไปยังเรจิสทรียังอยู่ในแผนงาน

ทำไมจึงมีหลายสัญญาอนุญาต?

โครงการที่ต่างกันมีความต้องการสัญญาอนุญาตต่างกัน BSD และ MIT ผ่อนปรน Apache-2.0 มีการให้สิทธิบัตร และตัวเลือก GPL สนับสนุน copyleft เลือกอันที่เหมาะกับสถานการณ์ของคุณ

ฉันจะรายงานข้อบกพร่องหรือขอฟีเจอร์ได้อย่างไร?

เปิด issue บนรีโพซิทอรี GitHub หรืออีเมลถึง joel@joelparkerhenderson.com.