https://github.com/thatgibbyguy/ply
ply - A ratio based CSS Framework in SCSS.
https://github.com/thatgibbyguy/ply
css-framework grid ratio scss smacss
Last synced: 3 months ago
JSON representation
ply - A ratio based CSS Framework in SCSS.
- Host: GitHub
- URL: https://github.com/thatgibbyguy/ply
- Owner: thatgibbyguy
- License: mit
- Created: 2015-12-06T17:21:12.000Z (over 10 years ago)
- Default Branch: master
- Last Pushed: 2023-01-05T20:39:16.000Z (over 3 years ago)
- Last Synced: 2024-04-14T22:19:49.816Z (about 2 years ago)
- Topics: css-framework, grid, ratio, scss, smacss
- Language: SCSS
- Homepage:
- Size: 6.46 MB
- Stars: 18
- Watchers: 4
- Forks: 7
- Open Issues: 8
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# ply
A ratio-based, AI-ready CSS framework with dark mode, accessibility, and a small footprint.
**~21KB gzipped. No JavaScript. No build step. One `` tag.**
## Install
### npm + Sass (recommended)
For real projects, install ply and import the SCSS source to get the full color palette, variables, and mixins.
```sh
npm install ply-css
```
```scss
@use "ply-css/src/scss/ply" as *;
```
### CDN (prototyping)
```html
```
### Git
```sh
git clone https://github.com/thatgibbyguy/ply.git
```
## Why ply?
CSS frameworks were designed for humans reading documentation. But increasingly, the first consumer of your framework is an AI — a coding agent in Replit, Claude, Cursor, or Copilot generating a UI from a prompt.
- **Start semantic** — ply automatically styles ``, ``, ``, ``, ``, ``, and more. Start with what HTML gives you, then reach for classes when you need them.
- **AI-native** — ships with `PLY.md` (AI instruction file) and `ply-classes.json` (machine-readable class reference). Class names are predictable: `.alert-blue`, `.btn-sm`, `.unit-50`.
- **Accessible by default** — `:focus-visible` outlines on all interactive elements (including `` and legacy components), `prefers-reduced-motion`, `prefers-color-scheme` dark mode, semantic HTML styling, WCAG AA contrast in both light and dark themes. Published [VPAT 2.5](https://plycss.com/docs/vpat) documenting conformance against all WCAG 2.1 Level A and AA criteria.
- **Small footprint** — ~21KB gzipped (full), ~17KB (core). No JavaScript runtime, no build step, no tree-shaking.
- **Ratio-based grid** — think in percentages, not arbitrary columns. `unit-50` is 50%, `unit-33` is 33%. Responsive prefixes: `tablet-unit-*`, `phone-unit-*`.
- **Custom theming** — override `--ply-*` CSS custom properties to create any theme. Light and dark modes built in.
## Quick Start
```html
Hello, ply
A two-column layout. Stacks on tablet and below.
Get Started
```
## Bundles
| Bundle | File | Description |
|--------|------|-------------|
| Full | `ply.min.css` | Everything — grid, typography, forms, buttons, navigation, notifications, labels, dropdown, loader, helpers |
| Core | `ply-core.min.css` | Grid, typography, forms, buttons, navigation, notifications, essential helpers |
| Essentials | `ply-essentials.min.css` | Grid + helpers only |
## Dark Mode
ply respects `prefers-color-scheme` automatically. No configuration needed.
To force a mode:
```html
```
## Custom Themes
Override `--ply-*` CSS custom properties to create any theme:
```css
[data-theme="warm"] {
--ply-bg-body: #faf5f0;
--ply-color-body: #1c1917;
--ply-color-headings: #44240e;
--ply-color-accent: #92400e; /* Icons, badges, section accents */
--ply-btn-default-bg: #92400e; /* Primary button + links */
--ply-btn-secondary-bg: #78350f; /* Secondary button */
--ply-btn-border-radius: 0.5rem; /* Button corner radius */
--ply-font-body: Palatino, Georgia, serif;
--ply-font-heading: Palatino, Georgia, serif;
/* ... */
}
```
```html
```
See `snippets/custom-theme.html` for a full working example.
## Icons
ply doesn't include icons. [Lucide](https://lucide.dev) is recommended — lightweight, clean, and pairs well with ply. Any icon library works.
```html
lucide.createIcons();
```
## AI Integration
For AI agents (Claude, Cursor, Copilot, Replit AI):
- **`PLY.md`** — complete class reference, usage rules, anti-patterns, and snippets
- **`ply-classes.json`** — machine-readable class map for programmatic tool use
- **`snippets/`** — copy-paste HTML files for common patterns (dashboard, login, contact form, etc.)
ply is standalone — it should not be used alongside Tailwind, Bootstrap, or other CSS frameworks.
## Development
```sh
npm install
npm run build # Compile all bundles
npm run watch # Watch for changes
npm run lint # Run stylelint
```
### Tech
- [Sass](https://sass-lang.com/) (modern `@use`/`@forward` modules)
- [PostCSS](https://postcss.org/) + [Autoprefixer](https://github.com/postcss/autoprefixer) + [cssnano](https://cssnano.github.io/cssnano/)
## Compliance
ply targets ADA Title II (28 CFR Part 35) / WCAG 2.1 AA compliance at the framework level. A [VPAT 2.5](https://plycss.com/docs/vpat) is published documenting conformance against all Level A and Level AA success criteria.
## Documentation
Full interactive docs at [plycss.com](https://plycss.com) — browse every class with live examples, search the entire framework, and copy-paste code snippets.
## Roadmap
- CSS logical properties for native RTL support (replaces bolt-on mirroring)
- Build-time class validator / VS Code extension
- Automated accessibility test suite (VPAT evidence)
## Contributing
Fork this repo and create a Pull Request with your changes.
## License
MIT
Special thanks to [imperavi](https://imperavi.com/) for creating the CSS framework I could only envision at the time.