awesome-python 设计系统全解DESIGN.md 如何定义一套 OKLCH 暖色编辑风参考网站【免费下载链接】awesome-pythonThe definitive list that answers I want to do X in Python, which tool should I use?项目地址: https://gitcode.com/GitHub_Trending/aw/awesome-pythonDESIGN.md 是 awesome-python 项目网站的设计系统规范文档它把视觉决策收敛为一份可执行的“宪法”OKLCH 暖色色板、Cormorant Garamond Manrope 的字体搭配、单一宽度上限的表格驱动布局以及一整套“发版前必须跑一遍”的审计清单。本文沿该文档的章节脉络逐节展开并结合 website/static/style.css 与 website/static/main.js 的真实实现说明每个设计约束在代码里如何落地读完你可以掌握“设计令牌 → CSS 变量 → 组件行为”这条完整链路以及如何在保持视觉一致性的前提下安全地迭代一个参考型网站。文档定位与总体设计哲学awesome-python.com 是一个可搜索、可筛选的约 650 个精选 Python 项目索引。DESIGN.md 开宗明义地定义了它的产品属性这是一个参考工具不是落地页也不是 GitHub README 的镜像。文档采用 Google Stitch 的 DESIGN.md 格式编写顶部 YAML frontmatter 只编码version: alpha、name和description三项并且明确声明令牌真源source of truth是website/static/style.css文档中同时给出 OKLCH 规范值与近似 hex 值以兼容只认 hex 的 lint 工具。文档用三个词概括整体气质opinionated有立场、confident自信、dense信息密集。目标读者是每天写 Python 的中高级工程师他们带着具体问题而来——“现在哪个 HTTP client 好用”“X 场景还有维护活跃的 ORM 吗”“任务队列大家在用什么”——并且以快速扫读的方式消费页面奖励密度与简洁文案惩罚营销腔。三个核心任务Jobs to be done快速为某个具体需求找到库搜索 标签筛选一眼比较候选项star 数、最后提交时间、标签、一行描述在点击跳转前确认项目还“活着”。语气Voice要求编辑腔editorial每个词都要挣得自己的位置自信而非好斗不炒作冷静权威——更接近精编的技术参考书OReilly 索引、好的 man page而非博客或产品站。情感目标是信任、效率与工艺感读者应感到这份列表是被有品味的人编辑过的。视觉参照与反参照是文档中最有辨识度的部分参照系placestoread表格、展开行、排序、页脚的主要视觉模型意味着“密集单页列表 点击行内展开并缩进在 Name 列下 可排序表头 最少装饰”杂志参考页The Economist、FT Weekend、Monocle野外指南书curated、functional、hand-made图书馆卡片目录密集表格信息、优秀排版、不为装饰而装饰。反参照系严格回避泛型深色开发者工具风近黑底上的青色、霓虹渐变、VSCode 调色板仪表盘、终端绿等宽字体品牌感其他 awesome-* 站点纯 README 倾倒、裸链接列表、没有声音SaaS 营销页大号指标计数器、证言卡片、特性网格、定价分层、“加入 10000 开发者”式社交证明条。五条设计原则列表是主角。Hero、赞助条、CTA 都存在但不许与表格争夺注意力密度即特性。优先用表格和紧凑节奏而不是每张卡片塞一个事实编辑式排版优于装饰。视觉趣味来自衬线/无衬线搭配、字号层级与留白而非渐变、阴影、徽章或标题上方的图标盒暖不冷。中性色向暖色相偏移OKLCH 色相约 55–80纯灰与冷蓝不属于本系统一个观点。没有深色模式、没有主题选择器、没有备选色板——一致性本身就是策展的信号。颜色系统暖色编辑调色板与令牌纪律颜色部分是全篇约束最密集的一节仅浅色主题color-scheme: light只用 OKLCH不用 HSL、不用 hex。所有令牌值都可以在 style.css 的:root区段 中逐一对应验证文档与代码完全一致。表面色Surfaces令牌OKLCH 值近似 hex用途--bg-pageoklch(96.8% 0.018 80)≈#FBF3E7奶油/象牙画布body 底色--bg-page-topoklch(95.2% 0.018 78)≈#F7EFE3body 顶部渐变起点--bg-page-endoklch(98.4% 0.01 80)≈#FCF8F0body 底部渐变终点--bg-paperoklch(98.6% 0.01 80)≈#FEFAF3内容外壳的暖白--bg-paper-strongoklch(95.7% 0.016 76)≈#F7F0E5赞助条、CTA 背景等着色纸张--hero-bg-start/mid/endoklch(14% 0.03 32)→oklch(19% 0.035 35)→oklch(28% 0.05 42)≈#130503→#22120B→#3D2014Hero 暗色大地系渐变--footer-bgoklch(16% 0.025 35)≈#170906暗暖炭色页脚其中 body 背景的实现值得注意它不是单色而是左上角一个柔和径向高光叠加一条纵向三段渐变见 style.css 中 body 规则background: radial-gradient(circle at top left, oklch(100% 0 0 / 0.72), transparent 28rem), linear-gradient(180deg, var(--bg-page-top), var(--bg-page) 24rem, var(--bg-page-end));墨色Ink--inkoklch(22% 0.02 55)≈#221812正文、--ink-soft≈#4A4039次级文案、--ink-muted≈#72665Emeta 行、题注、静态标签外加--line/--line-strong用于发丝线与分隔线style.css 中分别为oklch(83% 0.02 70)与oklch(64% 0.035 62)。强调色Accent暖棕红仅留给交互元素令牌OKLCH 值近似 hex用途--accentoklch(58% 0.16 45)≈#C4530F主强调色--accent-deepoklch(44% 0.15 42)≈#922900链接文字、hover--accent-softoklch(92% 0.045 55)≈#FDDDC9筛选标签的着色底--accent-underlineoklch(58% 0.16 45 / 0.4)≈#C4530F66低强调 text-decoration-color颜色使用规则是本设计系统最有“纪律感”的部分任何新颜色一律用 OKLCH不是 HSL不是 hexaccent 令牌保留给交互元素。可点击的筛选标签.tag用--accent-soft底配--accent-deep文字交互链接状态.col-name a:hover、.sponsor-link:hover、.hero-action-primary、.back-to-top、CTA使用 accent 令牌。这一条可以直接在源码里验证——.tag 的基态规则 就是background: var(--accent-soft); color: var(--accent-deep)非交互元素必须用 ink 令牌放在--bg-paper-strong或--bg-paper上绝不许碰 accent.source-badge用--ink-soft.sponsorship-body code用--ink。设计意图很直白——用户不应把静态装饰误认为可点击的东西同一角色全局使用同一令牌禁止在某个规则里埋一条一次性color: oklch(...)内联值。文档还记录了明确的“厌恶项”不许用绿色选色时用户明确否决过暖棕红、象牙白与暗大地色是既定系统不许青色、霓虹渐变、纯灰、冷蓝。排版字体搭配、字号刻度与“血泪经验”规则字体搭配是写死的、不可更换的一对展示字体Cormorant Garamond衬线仅 600 字重正文字体Manrope无衬线400 / 600 / 700 / 800。style.css 中对应为--font-display: Cormorant Garamond, Georgia, serif与--font-body: Manrope, Avenir Next, Segoe UI, sans-serif均带系统字体回退。字号刻度Scale角色令牌尺寸字体字重备注Hero 标题字面clampclamp(4.5rem, 11vw, 8.5rem)Cormorant Garamond600杂志封面级全站仅 Hero 使用一次大正文--text-lg1.125remManrope400内容密集段落正文--text-base1rem16pxManrope400正文底线不许更小Meta/次级--text-sm0.95remManrope400 / 600meta 行、次级文案题注/药丸--text-xs0.8rem12.8pxManrope600 / 700最小令牌药丸、徽章、标签、脚注style.css 的令牌定义 与上表逐一对应。真正体现文档价值的是随后的“血泪经验”hard-won字号规则每一条都标注了“不要放宽”正文底线 16px不许更小任何文字含药丸、徽章、标签、题注、脚注的绝对最小字号是 12px0.75rem——更小的值会撞上 Chrome 的默认最小字号防线在不同浏览器与用户辅助功能设置下渲染不一致。代码中最小令牌请用var(--text-xs)0.8rem拿不准时就往大选一档。文档直言“用户已跨 8 个会话把尺寸向上修正了 11 次以上”——页脚、meta 行、展开内容、标签、标题默认都偏小。绝不在无人要求时调小既有尺寸相邻标题层级之间渲染尺寸差至少 0.25rem表格行号左对齐、无前导零零填充方案被试过并被否决永远不用text-transform大小写直接写在标记里。布局单一宽度上限与“默认无内部限宽”布局章节的核心立场非常反直觉却是这个项目被反复修正后沉淀下来的结论全站只有一个宽度上限--shell-max: 84rem约 1344px通过.section-shell应用。宽屏显示器是默认观看场景。不要给任何元素加max-width——段落、卡片、表格单元格、展开行、CTA 背景、赞助描述、Hero 副文案、列表项都不许。用户已经反复删除过狭窄的内部限宽56ch、65–75ch之类。“把行长控制在 65–75ch”的通用排版教条在这里不适用明确忽略宽幅下的可读性改由垂直节奏、行高与模块化字号刻度承担。如确需为某个元素加宽度上限先带着具体理由询问。从源码结构看这一原则贯彻得很彻底.section-shell 的宽度实现 是width: min(100%, calc(var(--shell-max) (var(--shell-pad) * 2)))即上限只作用于 shell 层连表格首末列的对齐也复用了同一个 shell 计算style.css 中padding-left: max(var(--shell-pad), calc(50vw - (var(--shell-max) / 2) var(--shell-pad)))让表格内容在宽屏下精确贴住 shell 边缘。其余布局细则Shell 内边距--shell-pad: clamp(1.25rem, 3vw, 2.5rem)对称留白logo 左间距等于右间距表头与正文的列内边距一致flex 与 grid 中用gap而非子元素 margin逻辑属性margin-inline、padding-block优先于物理属性margin-left、padding-top间距与字号用rempx只用于边框和阴影所有颜色与重复值都走 CSS 自定义属性兄弟组件卡片列表、网格项共享完全相同的间距布局用 flexbox 或 grid避免 float 与绝对定位真正的覆盖层场景除外焦点环、吸顶表头永远不用!important而是修正特异性。层次与深度色调分层而非重阴影深度来自色调分层tonal layers而不是重阴影页面是安静的暖色画布--bg-page内容外壳是略亮的纸面--bg-paper赞助条、CTA 背景与内联装饰块再抬到--bg-paper-strongHero 是全站唯一使用真实“氛围”的地方微妙网格 缓慢流光sheen 暗色大地底上的暖色径向渐变--hero-bg-start→--hero-bg-mid→--hero-bg-end且流光等所有动效尊重prefers-reduced-motion页脚是--footer-bg上的单色块内部没有渐变全项目只允许两种深度处理搜索输入框组合 1px 内嵌高光--search-inset与柔和暖色投影--search-shadow聚焦时加强为--search-focus-shadow主 CTA 按钮.hero-action-primary带一个暖色投影作为按压暗示。两者都是柔和、暖色调、且绑定交互元素。卡片、面板、行、静态装饰上不许出现新的投影不许把玻璃拟态当默认装饰不许弹跳或弹性缓动——真实物体是平滑减速的。搜索框恰好是第一种“允许的深度处理”的样板style.css 中的投影栈写得很清楚inset 0 1px 0 var(--search-inset), 0 1.4rem 2.6rem -2.1rem var(--search-shadow)——一个 1px 内嵌高光加一个被大负 spread 收束的软暖影聚焦时再叠加--search-focus-shadow。形状语言小药丸、大直角形状语言可以概括为一句话小的用 999px 药丸大的用 0 圆角。药丸border-radius: 999px用于标签、搜索框、赞助 logo 芯片、来源徽章、back-to-top、主 CTA 按钮0.4rem只出现在一个地方.sponsorship-body内联code。文档明确反对引入令牌化圆角刻度——项目不需要容器直接使用页面表面而不是圆角面板。需要面板时小芯片用药丸、大表面用直角不允许超过 1px 的border-left/border-right作为彩色强调条用在卡片、列表项、callout 或告警上需要换结构。组件词汇表表格驱动的页面组件词汇刻意做得很小、以表格为中心真源同样是 style.css。逐个看核心组件及其源码证据表格驱动索引页面主角吸顶表头、可排序列、点击展开的行缩进在 Name 列下视觉模型来自 placestoread明确“不是卡片网格”。源码中吸顶表头 用position: sticky; top: 0; z-index: 12加半透明底--thead-bg实现滚动时依然可读的列头行状态用令牌分层hover 时--row-hover底色.row 规则键盘聚焦时加一条 3px 的 accent 内嵌指示条box-shadow: inset 3px 0 0 var(--accent)style.css展开时行底为--row-open-start → --row-open-end的纵向渐变style.css。交互行为在 main.js 中有完整实现与文档描述一一对应排序sortRows()先为每行缓存一次排序值row._sortVal避免每次比较都查 DOM再比较排序表头通过th[data-sort]点击触发并同步aria-sort属性main.js行展开点击行切换aria-expandedEnter/Space 同样可切换展开行作为兄弟节点插入表格main.js筛选与 URL 同步筛选状态写入 URL 的sort参数如name、stars、downloads、commit-time标签筛选映射到分类 URLmain.js让每个筛选结果可被直接链接、可被搜索引擎收录搜索框支持键盘可访问性搜索词匹配不仅看行文本还会合并展开行内容main.js 附近逻辑。筛选标签.tag--accent-soft底 --accent-deep文字、药丸形状hover 切换为--highlight底 --tag-hover-border描边 ink 文字激活态用--tag-active-start → --tag-active-end暖色渐变 hero 墨色文字。这些状态全部可以在 .tag 规则 中验证hover 态background: var(--highlight)active 态linear-gradient(135deg, var(--tag-active-start), var(--tag-active-end))。一个工程细节.tag::after用一个 44×44 的不可见扩展区style.css扩大了点击热区这对密集排布的小标签是关键的可用性设计。标签变体tag-group、tag-source今天继承基础.tag样式只在窄屏下有差异tag-group在 960px 以下隐藏——只有出现真实视觉差异需求时才新增变体。Hero杂志封面级标题、暗色大地底、kicker 与 proof 微文案、主 CTA 按钮使用--hero-btn-start/--hero-btn-end渐变微妙网格加缓慢流光尊重prefers-reduced-motion。赞助条位于 README 头部--bg-paper-strong底编辑式排版而非 logo 墙赞助链接共享全局 accent 处理。CTA暖色--cta-bg、shell 内全幅出血按钮本身用 accent 令牌。页脚暗暖炭色属于同一体系页脚链接共享全局 hover 与 focus 处理。搜索框药丸输入框--search-inset内嵌高光 --search-focus-ring聚焦环聚焦投影用--search-focus-shadow。来源徽章/内联代码--bg-paper-strong上的静态装饰.source-badge用--ink-soft文字呈药丸形.sponsorship-body code用--ink文字与全站唯一一处0.4rem圆角。永远不用 accent。同级一致性检查发布任何视觉改动前必跑Hover 与 focus 状态某类链接获得某种处理其同级链接hero 顶栏、页脚、项目名、赞助名、展开 meta必须共享标签变体继承基础.tag样式只在有真实差异处偏离排版层级扮演相同角色的标签共享尺寸、字重与字距对称留白logo 左间距等于右间距表头与正文列内边距一致基于角色的颜色令牌同一角色处处同一令牌。Dos and Donts 速查文档把规则压缩成一张可执行的清单这里完整保留Do让表格保持焦点accent 令牌只给交互元素密度优先于留白扩张发布视觉改动前检查同级元素任何新颜色都用 OKLCH。Dont给任何东西加内部max-widthshell 管宽度引入绿、青、霓虹、纯灰、冷蓝加深色模式、主题选择器或备选色板用渐变文字background-clip: text只许纯色用!important用text-transform用大于 1px 的border-left/border-right作强调条用弹跳或弹性缓动把玻璃拟态当默认装饰模仿泛型深色开发者工具站、其他 awesome-* 站或 SaaS 营销页。窄屏行为与迭代审计清单文档明确用户会主动测试 960px与 680px两档视口窄屏必须保持功能完整不许砍掉用户可能需要的功能排序暗示、筛选芯片、合理情况下的吸顶表头。隐藏是最后手段且必须给出理由任何布局改动后都要在窄视口跑一遍playwright-cli验证。“迭代指南”要求在任何生成或修改界面后跑一遍六项审计任何一项不过就返工宽度上限检查每个 section、卡片、段落、表格单元格、展开行、CTA、赞助描述、hero 副文案。只有.section-shell--shell-max: 84rem可以限宽别处出现max-width就是错的Accent 保留grep 改动后的 CSS 中--accent、--accent-deep、--accent-soft每个命中必须对应一个交互元素链接、按钮、焦点环、筛选标签。静态装饰必须用 ink 令牌落在--bg-paper-strong或--bg-paper上形状语言容器是直角或药丸4px–16px 之间的圆角都可疑唯一例外是.sponsorship-body code的那处0.4rem字号确认没有渲染文字低于 12px若某尺寸在 27 英寸屏上对中级以上读者显得小就升一档永远不调小既有尺寸同级一致性与最近的同级元素兄弟链接类型、兄弟标签变体、兄弟标签对比 hover、focus、颜色令牌与留白除非有书面理由否则必须一致窄视口在 960px 与 680px 下跑playwright-cli排序暗示、筛选芯片、吸顶表头必须仍然可用。这套清单的实质是把 DESIGN.md 从“设计描述”变成了“可 grep、可执行的验收标准”——第 2 项甚至直接给出了验证命令的思路grep 三个 accent 令牌让审计不依赖记忆或审美判断。已知缺口与验证方式文档诚实地列出三个已知缺口Known Gaps颜色格式偏离 Stitch 规范官方 lint 要求 hex sRGB而本项目强制style.css使用 OKLCH。Colors 节的解法是双轨呈现OKLCH 为规范值hex 为面向 lint 工具的近似值YAML frontmatter 保持最小只编码version、name、description三项。项目没有消费令牌级 frontmatter 的 JSON/Figma 导出管道所以其余内容优先用散文表达没有正式的间距或圆角刻度代码库使用clamp()与临时 rem 值而非令牌化刻度——强行补一套刻度是“发明”不是“记录”。验证Verification一节则给出工作流底线任何前端改动之后都用playwright-cli在真实浏览器里做视觉验证——检查布局、响应式与交互行为不得仅凭代码就宣称某个 UI 改动可用。结合上文可见这条要求与 style.css 中prefers-reduced-motion、main.js 中aria-sort/aria-expanded的实现共同构成了“规范 → 实现 → 审计 → 真机验证”的闭环。小结DESIGN.md 在这类项目里的方法论价值awesome-python 的 DESIGN.md 示范了设计系统文档的一种高信息密度写法令牌与代码双向锚定——每个颜色、字号、形状结论都能在 website/static/style.css 的:root与组件规则中逐条复核文档不是愿景而是契约把交互行为也纳入设计词汇——表格展开、排序、筛选在 main.js 中的可访问性实现aria-sort、aria-expanded、URL 同步与 CSS 状态令牌是一体的设计产物规则带“为什么”和“否决史”——“最小 12px”“正文 16px 底线”“行号不加前导零”都记录了被否决的替代方案与原因让后来者知道哪条规则不能碰可执行的审计代替主观评审——宽度上限检查、accent 令牌 grep、窄视口 playwright 验证让“是否符合设计系统”成为可重复回答的问题。对维护者而言修改这套系统的入口就是 DESIGN.md 的迭代指南对贡献者而言按“窄屏可用、令牌复用、无内部限宽”三条底线检查自己的改动即可与该参考站的设计纪律保持一致。【免费下载链接】awesome-pythonThe definitive list that answers I want to do X in Python, which tool should I use?项目地址: https://gitcode.com/GitHub_Trending/aw/awesome-python创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考