@cawalch / porchlight

Porchlight是一个无依赖的原生css框架， 主题web应用程序。看词根 自述 和 这个 文档网站 以获得完整的指导。

在服务器模板、html片段和Alpine组件中使用稳定类。 看到 集成指南 用于那些工作流和可选的CSS模块定制。

安装

pnpm add @cawalch/porchlight
# or
bun add @cawalch/porchlight
# or
npm install @cawalch/porchlight

完整的包

主要导出是一个预构建的样式表。通过解析包导入 你的应用绑定器，并加载一次生成的CSS条目。浏览器无法解析 这些裸包名称直接；使用下面的静态HTML而不使用捆绑器。

@layer porchlight, app;
@import "@cawalch/porchlight";

@layer app {
  /* your product styles */
}

较小的包

如果你的应用只使用了几个组件，那就从 core.css，然后导入 你需要的东西。

@layer porchlight, app;

@import "@cawalch/porchlight/core.css";
@import "@cawalch/porchlight/layout.css";
@import "@cawalch/porchlight/components/button.css";
@import "@cawalch/porchlight/components/field.css";
@import "@cawalch/porchlight/components/card.css";
@import "@cawalch/porchlight/utilities.css";

core.css 包括层顺序，重置，令牌，主题和基本样式。 组件文件依赖于这些令牌，所以加载 core.css 第一。 对于拆分按钮，也要加载 button.css 之前 split-button.css;它的两个 片段使用按钮组件。 porchlight copy --components split-button 包括 button.css 自动，而CSS @import 保持明确的。

如果你想要整个实用框架而不需要实验增强 语法、使用 compat.css． 它包括核心、布局、所有组件和 公用事业，但遗漏 enhancements.css.

@layer porchlight, app;
@import "@cawalch/porchlight/compat.css";

公共CSS API

Porchlight公共钩子使用 pl- 命名空间，以避免冲突 应用CSS和其他框架：

• 组件: .pl-c-button， .pl-c-card__title
• 布局原语: .pl-l-stack， .pl-l-cluster
• 公用事业: .pl-u-sr-only， .pl-u-flow
• 组件和实例令牌： --pl-c-card-padding， --pl-l-stack-gap
• Framework-wide属性: data-pl-theme， data-pl-density

组件本地属性，例如 data-tone， data-selected，以及ARIA 当作用域在Porchlight组件类下时，状态保持不带前缀。

静态HTML和CLI工具

对于服务器渲染的应用程序、快速原型或直接复制资产的管道，Porchlight包括命令行界面（CLI）：

# Scaffold a starter HTML file
npx --no-install porchlight init

# Scaffold with a custom output path, local stylesheet, and title
npx --no-install porchlight init --out public/index.html --local --title "My App"

# Inspect design tokens in the terminal
npx --no-install porchlight tokens
npx --no-install porchlight tokens radius
npx --no-install porchlight tokens --group Fonts

# Output matching tokens as JSON
npx --no-install porchlight tokens --group Colors --json

# Copy static CSS files for non-bundler pipelines
npx --no-install porchlight copy --out public/porchlight --compat

<link rel="stylesheet" href="/porchlight/compat.css" />

这些url假定您的服务器公开 public/ 在 /;根据你的 资产挂载或部署基础路径。

对于较小的静态切片，请命名您使用的组件（并可选择请求最小化输出）：

npx --no-install porchlight copy --out public/porchlight --components button,field --layout --utilities --min

<link rel="stylesheet" href="/porchlight/core.min.css" />
<link rel="stylesheet" href="/porchlight/layout.min.css" />
<link rel="stylesheet" href="/porchlight/components/button.min.css" />
<link rel="stylesheet" href="/porchlight/components/field.min.css" />
<link rel="stylesheet" href="/porchlight/utilities.min.css" />
<link rel="stylesheet" href="/app.css" />

在 app.css，在重写之前声明你的层顺序：

@layer porchlight, app;

@layer app {
  /* app overrides */
}

生成的 dist/porchlight.manifest.json 列出每个打包的CSS文件， 组件名称，以及脚本的推荐复制顺序。

轻快地

Vite解析CSS导入包。从您的应用程序或导入一个CSS条目 链接到Vite的HTML入口；裸包导入不是浏览器url。

@layer porchlight, app;
@import "@cawalch/porchlight/core.css";
@import "@cawalch/porchlight/components/button.css";
@import "@cawalch/porchlight/components/data-table.css";
@import "@cawalch/porchlight/utilities.css";

如果方便的话，你也可以从JS/TS条目中导入CSS：

import "@cawalch/porchlight/core.css";
import "@cawalch/porchlight/components/button.css";
import "./app.css";

对于生产版本，设置一个与您支持的浏览器匹配的CSS目标。 文档构建使用 build.cssTarget: "chrome149" 为了保留本土色彩 功能。这是Chromium的目标，而不是跨浏览器支持的保证。 完整的包也与Vite 8.2.1的默认目标在一个小的 亮/暗消费类灯具。更改目标后重新检查渲染输出 或缩小镜;看到 Vite的CSS目标选项.

面包和其他静态管道

Bun可以安装Porchlight并运行它的复制助手。使用Bun作为包 manager与发送CSS是分开的 bun build.

验证与 Bun 1.4.2和Porchlight 0.13.1：

对于Bun的CSS打包器，放入这个 app.css，然后跑 bun build ./app.css --outdir ./dist：

@layer porchlight, app;
@import "@cawalch/porchlight/compat.css";

在页面中加载发出的样式表；单独的CSS构建不会附加它 到DOM。基本的按钮/卡片颜色以浅色和深色为主题； 这不是对每个组件或未来的Bun版本的保证。

要获得完整的bundle，可以显式地运行已安装的CLI和Bun的运行时：

bunx --bun --no-install porchlight copy --out public/porchlight --full

<link rel="stylesheet" href="/porchlight/porchlight.css" />

将该目录作为静态文件提供。将复制的CSS返回给Bun's HTML/CSS打包器重新引入了解析器的限制。 --bun 避免了CLI的 节点工作; --no-install 使用本地安装包。 看到 Bun的CSS捆绑器 和 Bunx运行时选择.

令牌

Porchlight为编辑器自动完成提供生成的令牌元数据， 验证和自定义工具。

import tokenDoc, { tokenGroups } from "@cawalch/porchlight/tokens";

console.log(tokenDoc.tokens["--pl-color-accent"].value);
console.log(tokenGroups.map((group) => group.name));

JSON也可用：

import tokens from "@cawalch/porchlight/tokens.json" with { type: "json" };

出口

有关记录所有51个组件（主选择器、模块化导入路径、最小化包、依赖项和描述）的离线参考，请参见 COMPONENTS.md.

层序

Porchlight包含了每条规则 @layer porchlight.*． 声明你的应用程序层 在Porchlight之后，产品CSS赢得了无特异性的战斗。

不要通过 layer(...) 这些进口。Porchlight已经自我分层了。

浏览器支持

铬是主要的测试目标；Firefox和WebKit烟雾有限 报道。 @scope 需要Firefox 146或更高版本，而不是Firefox 135。Porchlight使用 现代CSS包括 @layer， @scope， @propertyOKLCH, light-dark()， color-mix()， :has()，容器查询，弹出窗口API， 以及锚的定位。看到 浏览器支持指南 对于完整的特征矩阵。