@k9kbdev/roblox-css 0.1.0

package/LICENSE

@@ -0,0 +1,15 @@
+roblox-css — CSS-to-Roblox UI translation middleware
+Copyright (C) 2026 Kaleb Kougl
+
+This library is free software; you can redistribute it and/or modify it
+under the terms of the GNU Lesser General Public License as published by
+the Free Software Foundation; either version 3 of the License, or (at
+your option) any later version.
+
+This library is distributed in the hope that it will be useful, but
+WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser
+General Public License for more details.
+
+You should have received a copy of the GNU Lesser General Public License
+along with this library. If not, see <https://www.gnu.org/licenses/>.

package/README.md

@@ -0,0 +1,245 @@
+# roblox-css
+
+**Write CSS. Get Roblox UI.**
+
+[![License: LGPL-3.0](https://img.shields.io/badge/License-LGPL--3.0-blue.svg)](https://www.gnu.org/licenses/lgpl-3.0)
+
+A CSS-to-Roblox UI translation middleware for [roblox-ts](https://roblox-ts.com). Write familiar web-style `style` props and get native Roblox engine primitives (`UDim2`, `UICorner`, `UIListLayout`, etc.) automatically.
+
+## What Problem Does This Solve?
+
+Building UI in Roblox requires manually wiring up `UDim2` sizes, parenting constraint instances (`UICorner`, `UIPadding`, `UIListLayout`), and juggling imperative property sets. `roblox-css` lets you write this instead:
+
+```tsx
+import { Box, Text, webStyle } from "roblox-css";
+
+const card = webStyle({
+  width: "200px",
+  height: "auto",
+  padding: "16px",
+  borderRadius: "12px",
+  backgroundColor: "#1a1a2e",
+  display: "flex",
+  flexDirection: "column",
+  gap: "8px",
+});
+
+// In your component:
+<Box style={card}>
+  <Text style={webStyle({ color: "white", fontSize: "18px" })}>
+    Hello, Roblox!
+  </Text>
+</Box>
+```
+
+The `webStyle()` function translates CSS properties into Roblox instance properties and child constraint elements. The wrapper components (`Box`, `Text`, `Button`, etc.) spread the result onto native Roblox instances.
+
+## Installation
+
+```bash
+npm install roblox-css
+```
+
+### Peer Dependencies
+
+**Required:**
+- `@rbxts/react` (>=17.0.0)
+
+**Optional** (only needed for motion primitives):
+- `@rbxts/ripple` (>=0.8.0)
+- `@rbxts/services`
+
+### Rojo Configuration
+
+Add `roblox-css` to your Rojo project file:
+
+```json
+{
+  "ReplicatedStorage": {
+    "roblox-css": {
+      "$path": "node_modules/roblox-css/src"
+    }
+  }
+}
+```
+
+## Primitives
+
+| Component | HTML Equivalent | Roblox Instance |
+|:---|:---|:---|
+| `<Box>` | `<div>` | `<frame>` |
+| `<Text>` | `<span>` / `<p>` | `<textlabel>` |
+| `<Button>` | `<button>` | `<textbutton>` |
+| `<Image>` | `<img>` | `<imagelabel>` |
+| `<Input>` | `<input>` | `<textbox>` |
+| `<ScrollBox>` | `<div style="overflow:auto">` | `<scrollingframe>` |
+
+### Motion Primitives
+
+Declarative, variant-driven animation (inspired by Framer Motion):
+
+| Component | Animates |
+|:---|:---|
+| `<MotionBox>` | `<frame>` |
+| `<MotionText>` | `<textlabel>` |
+| `<MotionButton>` | `<textbutton>` |
+| `<MotionImage>` | `<imagelabel>` |
+| `<MotionUIScale>` | `<uiscale>` |
+
+```tsx
+import { MotionBox, webStyle } from "roblox-css";
+
+<MotionBox
+  style={webStyle({ width: "100px", height: "100px" })}
+  animate={isHovered ? "hover" : "idle"}
+  variants={{
+    idle: { backgroundColor: "#1a1a2e", width: "100px" },
+    hover: { backgroundColor: "#e94560", width: "120px" },
+  }}
+  transition={new TweenInfo(0.3, Enum.EasingStyle.Quad)}
+/>
+```
+
+Requires `@rbxts/ripple` peer dependency.
+
+## Supported CSS Properties
+
+### Layout
+| CSS Property | Roblox Mapping |
+|:---|:---|
+| `width`, `height` | `Size` (UDim2) |
+| `minWidth`, `maxWidth`, `minHeight`, `maxHeight` | `UISizeConstraint` |
+| `display: "flex"` | `UIListLayout` |
+| `display: "grid"` | `UIGridLayout` |
+| `flexDirection` | `UIListLayout.FillDirection` |
+| `justifyContent` | `UIListLayout.HorizontalAlignment` / `VerticalAlignment` |
+| `alignItems` | `UIListLayout.HorizontalAlignment` / `VerticalAlignment` |
+| `gap` | `UIListLayout.Padding` |
+| `flexWrap` | `UIListLayout.Wraps` |
+| `order` | `LayoutOrder` |
+
+### Spacing
+| CSS Property | Roblox Mapping |
+|:---|:---|
+| `padding` (shorthand) | `UIPadding` (all sides) |
+| `paddingTop/Right/Bottom/Left` | `UIPadding` (individual) |
+
+### Visual
+| CSS Property | Roblox Mapping |
+|:---|:---|
+| `backgroundColor` | `BackgroundColor3` + `BackgroundTransparency` |
+| `color` | `TextColor3` + `TextTransparency` |
+| `opacity` | `BackgroundTransparency` / `ImageTransparency` |
+| `borderRadius` | `UICorner` |
+| `border` (shorthand) | `BorderSizePixel` + `BorderColor3` (style keywords like `solid` are optional) |
+| `boxShadow` | 9-slice `ImageLabel` overlay |
+| `background: "linear-gradient(...)"` | `UIGradient` |
+
+### Typography
+| CSS Property | Roblox Mapping |
+|:---|:---|
+| `fontSize` | `TextSize` |
+| `fontWeight` | `FontFace.Weight` |
+| `fontFamily` | `FontFace.Family` |
+| `fontStyle` | `FontFace.Style` |
+| `textAlign` | `TextXAlignment` |
+| `textVerticalAlign` | `TextYAlignment` |
+| `lineHeight` | `LineHeight` |
+| `textDecoration` | Rich text `<u>` / `<s>` tags |
+| `textTransform` | Component-level string transform |
+| `wordBreak` | Zero-width space injection |
+| `whiteSpace` | `TextWrapped` |
+| `textOverflow` | `TextTruncate` |
+
+### Other
+| CSS Property | Roblox Mapping |
+|:---|:---|
+| `overflow: "scroll"` | `ScrollingEnabled` |
+| `objectFit` | `ScaleType` |
+| `cursor` | Not supported in Roblox |
+| `visibility` | `Visible` |
+| `rotation` | `Rotation` |
+| `zIndex` | `ZIndex` |
+| `aspectRatio` | `UIAspectRatioConstraint` |
+| `autoSize` / `width: "auto"` | `AutomaticSize` |
+
+### Color Formats
+
+`roblox-css` supports all standard CSS color formats:
+
+- **Hex:** `#ff0000`, `#f00`, `#ff000080`
+- **RGB:** `rgb(255, 0, 0)`, `rgba(255, 0, 0, 0.5)`
+- **HSL:** `hsl(0, 100%, 50%)`, `hsla(0, 100%, 50%, 0.5)`
+- **Named:** All 148 CSS named colors (`red`, `cornflowerblue`, `rebeccapurple`, etc.)
+- **Roblox Color3:** Pass `Color3` instances directly
+
+### Dimension Formats
+
+- **Pixels:** `"100px"` or `100` (bare number = pixels)
+- **Percentage:** `"50%"` → `UDim` scale component
+- **Viewport:** `"100vw"`, `"50vh"` → viewport-relative
+- **Calc:** `"calc(100% - 20px)"`
+- **Auto:** `"auto"` → `AutomaticSize`
+
+## Type Safety
+
+`roblox-css` uses TypeScript **branded types** to prevent bypassing the middleware at compile time:
+
+```typescript
+// ✅ This works — value produced by webStyle()
+const style = webStyle({ width: "100px" });
+<Box style={style} />
+
+// ❌ This fails at compile time — raw object rejected
+const fake = { props: { Size: UDim2.fromOffset(100, 0) }, children: [] };
+<Box style={fake} />  // Type error: missing branded symbol
+```
+
+Four branded types enforce this: `WebStyleResult`, `ParsedDimension`, `ParsedColor`, `PaddingValues`.
+
+## Architecture
+
+See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for the full architectural deep-dive.
+
+```
+CSSProperties → webStyle() → { props, children }
+                   │
+        ┌──────────┼──────────┐
+        ▼          ▼          ▼
+   colorParser  dimParser  gradientParser
+        │          │          │
+        ▼          ▼          ▼
+     Color3     UDim/UDim2  UIGradient
+        │          │          │
+        └──────────┼──────────┘
+                   ▼
+           WebStyleResult (branded)
+                   │
+                   ▼
+          <Box style={result} />
+                   │
+           ┌───────┼───────┐
+           ▼               ▼
+     props spread    constraint children
+     on <frame>      (UICorner, UIPadding, ...)
+```
+
+## Running Tests
+
+Tests run natively inside Roblox Studio using `@rbxts/jest`:
+
+1. Build: `npx rbxtsc`
+2. Open `test-runner.project.json` in Roblox Studio via Rojo
+3. Run the Jest test plugin
+
+**Test coverage:** 1,419 assertions across 24 spec files covering every parser, primitive, and motion component.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+LGPL-3.0-only — see [LICENSE](LICENSE), [COPYING](COPYING), and [COPYING.LESSER](COPYING.LESSER).
+
+You may use `roblox-css` in proprietary projects without releasing your project's source code. However, any modifications to `roblox-css` itself must be released under LGPL-3.0.

package/default.project.json

@@ -0,0 +1,6 @@
+{
+  "name": "roblox-css",
+  "tree": {
+    "$path": "out"
+  }
+}

package/out/index.d.ts

@@ -0,0 +1,35 @@
+/**
+ * roblox-css — CSS-to-Roblox UI translation middleware.
+ *
+ * @license LGPL-3.0-only
+ * @author Kaleb Kougl
+ */
+export { webStyle, SHADOW_ASSET_ID, SHADOW_SLICE_CENTER } from "./styles/webStyle";
+export type { CSSProperties } from "./styles/CSSTypes";
+export { parseColor } from "./styles/colorParser";
+export { parseDimension, parsePadding } from "./styles/dimensionParser";
+export { parseGradient } from "./styles/gradientParser";
+export { NAMED_COLORS } from "./styles/namedColors";
+export { transitions } from "./styles/transitions";
+export { ParentSizeContext } from "./styles/ParentSizeContext";
+export { Box } from "./primitives/Box";
+export type { BoxProps } from "./primitives/Box";
+export { Text } from "./primitives/Text";
+export { Button } from "./primitives/Button";
+export { Image } from "./primitives/Image";
+export { Input } from "./primitives/Input";
+export { ScrollBox } from "./primitives/ScrollBox";
+export { InlineText } from "./primitives/InlineText";
+export { parseInlineImages, containsRichTextTags } from "./utils/parseInlineImages";
+export type { InlineSegment, TextSegment, ImageSegment } from "./utils/parseInlineImages";
+export { MotionBox } from "./primitives/MotionBox";
+export type { MotionBoxProps } from "./primitives/MotionBox";
+export { MotionText } from "./primitives/MotionText";
+export { MotionButton } from "./primitives/MotionButton";
+export { MotionImage } from "./primitives/MotionImage";
+export { MotionUIScale } from "./primitives/MotionUIScale";
+export { useVariantResolver, isAnimatable } from "./primitives/useVariantResolver";
+export type { MotionProps } from "./primitives/useVariantResolver";
+export { usePercentageConstraints } from "./primitives/usePercentageConstraints";
+export { setLogLevel, LogLevel } from "./logger";
+export type { DeepReadonly } from "./types";

package/out/init.luau

@@ -0,0 +1,57 @@
+-- Compiled with roblox-ts v3.0.0
+local TS = _G[script]
+local exports = {}
+--[[
+	*
+	 * roblox-css — CSS-to-Roblox UI translation middleware.
+	 *
+	 * @license LGPL-3.0-only
+	 * @author Kaleb Kougl
+	 
+]]
+-- Core engine
+local _webStyle = TS.import(script, script, "styles", "webStyle")
+exports.webStyle = _webStyle.webStyle
+exports.SHADOW_ASSET_ID = _webStyle.SHADOW_ASSET_ID
+exports.SHADOW_SLICE_CENTER = _webStyle.SHADOW_SLICE_CENTER
+-- Parsers (for advanced users)
+exports.parseColor = TS.import(script, script, "styles", "colorParser").parseColor
+local _dimensionParser = TS.import(script, script, "styles", "dimensionParser")
+exports.parseDimension = _dimensionParser.parseDimension
+exports.parsePadding = _dimensionParser.parsePadding
+exports.parseGradient = TS.import(script, script, "styles", "gradientParser").parseGradient
+-- Named colors
+exports.NAMED_COLORS = TS.import(script, script, "styles", "namedColors").NAMED_COLORS
+-- Transitions
+exports.transitions = TS.import(script, script, "styles", "transitions").transitions
+-- Context
+exports.ParentSizeContext = TS.import(script, script, "styles", "ParentSizeContext").ParentSizeContext
+-- Base primitives
+exports.Box = TS.import(script, script, "primitives", "Box").Box
+exports.Text = TS.import(script, script, "primitives", "Text").Text
+exports.Button = TS.import(script, script, "primitives", "Button").Button
+exports.Image = TS.import(script, script, "primitives", "Image").Image
+exports.Input = TS.import(script, script, "primitives", "Input").Input
+exports.ScrollBox = TS.import(script, script, "primitives", "ScrollBox").ScrollBox
+exports.InlineText = TS.import(script, script, "primitives", "InlineText").InlineText
+-- Inline image parser (for advanced users)
+local _parseInlineImages = TS.import(script, script, "utils", "parseInlineImages")
+exports.parseInlineImages = _parseInlineImages.parseInlineImages
+exports.containsRichTextTags = _parseInlineImages.containsRichTextTags
+-- Motion primitives
+exports.MotionBox = TS.import(script, script, "primitives", "MotionBox").MotionBox
+exports.MotionText = TS.import(script, script, "primitives", "MotionText").MotionText
+exports.MotionButton = TS.import(script, script, "primitives", "MotionButton").MotionButton
+exports.MotionImage = TS.import(script, script, "primitives", "MotionImage").MotionImage
+exports.MotionUIScale = TS.import(script, script, "primitives", "MotionUIScale").MotionUIScale
+-- Motion hooks
+local _useVariantResolver = TS.import(script, script, "primitives", "useVariantResolver")
+exports.useVariantResolver = _useVariantResolver.useVariantResolver
+exports.isAnimatable = _useVariantResolver.isAnimatable
+exports.usePercentageConstraints = TS.import(script, script, "primitives", "usePercentageConstraints").usePercentageConstraints
+-- Logger (for consumers who want to configure logging level)
+local _logger = TS.import(script, script, "logger")
+exports.setLogLevel = _logger.setLogLevel
+exports.LogLevel = _logger.LogLevel
+-- Types
+return exports

package/out/logger.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Minimal structured logger for roblox-css.
+ *
+ * Provides a `createLogger(source)` function that returns a logger object
+ * with `debug`, `info`, `warn`, `error`, and `fatal` methods.
+ *
+ * Each method accepts: (code: string, message: string, data?: object)
+ */
+export declare enum LogLevel {
+    DEBUG = 0,
+    INFO = 1,
+    WARN = 2,
+    ERROR = 3,
+    FATAL = 4
+}
+export declare function setLogLevel(level: LogLevel): void;
+export declare function createLogger(source: string): {
+    debug(code: string, message: string, data?: object): void;
+    info(code: string, message: string, data?: object): void;
+    warn(code: string, message: string, data?: object): void;
+    error(code: string, message: string, data?: object): void;
+    fatal(code: string, message: string, data?: object): void;
+};

package/out/logger.luau

@@ -0,0 +1,73 @@
+-- Compiled with roblox-ts v3.0.0
+--[[
+	*
+	 * Minimal structured logger for roblox-css.
+	 *
+	 * Provides a `createLogger(source)` function that returns a logger object
+	 * with `debug`, `info`, `warn`, `error`, and `fatal` methods.
+	 *
+	 * Each method accepts: (code: string, message: string, data?: object)
+	 
+]]
+local LogLevel
+do
+	local _inverse = {}
+	LogLevel = setmetatable({}, {
+		__index = _inverse,
+	})
+	LogLevel.DEBUG = 0
+	_inverse[0] = "DEBUG"
+	LogLevel.INFO = 1
+	_inverse[1] = "INFO"
+	LogLevel.WARN = 2
+	_inverse[2] = "WARN"
+	LogLevel.ERROR = 3
+	_inverse[3] = "ERROR"
+	LogLevel.FATAL = 4
+	_inverse[4] = "FATAL"
+end
+local currentLogLevel = LogLevel.WARN
+local function setLogLevel(level)
+	currentLogLevel = level
+end
+local function formatLogLine(level, source, code, message, data)
+	local line = `[{level}][{source}] {code}: {message}`
+	if data then
+		for k, v in pairs(data) do
+			line ..= ` {k}={tostring(v)}`
+		end
+	end
+	return line
+end
+local function createLogger(source)
+	return {
+		debug = function(self, code, message, data)
+			if currentLogLevel <= LogLevel.DEBUG then
+				print(formatLogLine("DEBUG", source, code, message, data))
+			end
+		end,
+		info = function(self, code, message, data)
+			if currentLogLevel <= LogLevel.INFO then
+				print(formatLogLine("INFO", source, code, message, data))
+			end
+		end,
+		warn = function(self, code, message, data)
+			if currentLogLevel <= LogLevel.WARN then
+				warn(formatLogLine("WARN", source, code, message, data))
+			end
+		end,
+		error = function(self, code, message, data)
+			if currentLogLevel <= LogLevel.ERROR then
+				warn(formatLogLine("ERROR", source, code, message, data))
+			end
+		end,
+		fatal = function(self, code, message, data)
+			warn(formatLogLine("FATAL", source, code, message, data))
+		end,
+	}
+end
+return {
+	setLogLevel = setLogLevel,
+	createLogger = createLogger,
+	LogLevel = LogLevel,
+}

package/out/primitives/Box.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Box.tsx — The foundational UI container component for Roblox.
+ *
+ * Provides a <div> equivalent that supports a web-like CSS syntax (`style` prop).
+ * It automatically translates CSS properties (e.g., `backgroundColor: "red"`) into
+ * Roblox engine equivalents (`BackgroundColor3`) and injects layout constraints
+ * like `UICorner`, `UIPadding`, `UIListLayout`, and `UIGridLayout` as child instances.
+ *
+ * Usage:
+ *   <Box style={{ width: "100%", height: "50px", backgroundColor: "#333", borderRadius: "8px" }}>
+ *     <textlabel Text="Hello World" />
+ *   </Box>
+ */
+import React from "@rbxts/react";
+import { CSSProperties } from "../styles/webStyle";
+import { DeepReadonly } from "../types";
+export type BoxProps = React.PropsWithChildren<React.ComponentProps<"frame">> & {
+    style?: CSSProperties;
+} & {
+    readonly _boxProps?: unique symbol;
+};
+export declare function makeBoxProps(props: Omit<BoxProps, "_boxProps">): DeepReadonly<BoxProps>;
+export declare const Box: React.ForwardRefExoticComponent<Omit<BoxProps, "ref"> & React.RefAttributes<Frame>>;

package/out/primitives/Box.luau

@@ -0,0 +1,103 @@
+-- Compiled with roblox-ts v3.0.0
+local TS = _G[script]
+--[[
+	*
+	 * Box.tsx — The foundational UI container component for Roblox.
+	 *
+	 * Provides a <div> equivalent that supports a web-like CSS syntax (`style` prop).
+	 * It automatically translates CSS properties (e.g., `backgroundColor: "red"`) into 
+	 * Roblox engine equivalents (`BackgroundColor3`) and injects layout constraints 
+	 * like `UICorner`, `UIPadding`, `UIListLayout`, and `UIGridLayout` as child instances.
+	 * 
+	 * Usage:
+	 *   <Box style={{ width: "100%", height: "50px", backgroundColor: "#333", borderRadius: "8px" }}>
+	 *     <textlabel Text="Hello World" />
+	 *   </Box>
+	 
+]]
+local _react = TS.import(script, TS.getModule(script, "@rbxts", "react"))
+local React = _react
+local useRef = _react.useRef
+local webStyle = TS.import(script, script.Parent.Parent, "styles", "webStyle").webStyle
+local ParentSizeContext = TS.import(script, script.Parent.Parent, "styles", "ParentSizeContext").ParentSizeContext
+local usePercentageConstraints = TS.import(script, script.Parent, "usePercentageConstraints").usePercentageConstraints
+local function makeBoxProps(props)
+	return props
+end
+local Box = React.forwardRef(function(props, ref)
+	local style = props.style
+	local children = props.children
+	local defaultProps = {
+		BackgroundTransparency = 1,
+		BorderSizePixel = 0,
+	}
+	local _object = table.clone(props)
+	setmetatable(_object, nil)
+	local explicitProps = _object
+	explicitProps.style = nil
+	explicitProps.children = nil
+	-- Merge user-provided Change listeners with our internal AbsoluteSize tracker
+	-- to avoid silently overwriting user event handlers.
+	local userChange = (props.Change) or {}
+	local _object_1 = table.clone(userChange)
+	setmetatable(_object_1, nil)
+	local mergedChange = _object_1
+	local setAbsSize
+	mergedChange.AbsoluteSize = function(rbx)
+		setAbsSize(rbx.AbsoluteSize)
+		-- Forward to user handler if present
+		local userHandler = userChange.AbsoluteSize
+		if userHandler ~= nil then
+			userHandler(rbx)
+		end
+	end
+	explicitProps.Change = nil
+	local bindingRef = useRef()
+	if not bindingRef.current then
+		local binding, setBinding = React.createBinding(Vector2.new(math.huge, math.huge))
+		bindingRef.current = {
+			binding = binding,
+			set = setBinding,
+		}
+	end
+	local _binding = bindingRef.current
+	local absSize = _binding.binding
+	setAbsSize = _binding.set
+	local percentageConstraint = usePercentageConstraints(style)
+	if style then
+		local parsedStyle = webStyle(style)
+		local _attributes = {
+			ref = ref,
+		}
+		for _k, _v in defaultProps do
+			_attributes[_k] = _v
+		end
+		for _k, _v in parsedStyle.props do
+			_attributes[_k] = _v
+		end
+		for _k, _v in explicitProps do
+			_attributes[_k] = _v
+		end
+		_attributes.Change = mergedChange
+		return React.createElement(ParentSizeContext.Provider, {
+			value = absSize,
+		}, React.createElement("frame", _attributes, parsedStyle.children, percentageConstraint, children))
+	end
+	local _attributes = {
+		ref = ref,
+	}
+	for _k, _v in defaultProps do
+		_attributes[_k] = _v
+	end
+	for _k, _v in explicitProps do
+		_attributes[_k] = _v
+	end
+	_attributes.Change = mergedChange
+	return React.createElement(ParentSizeContext.Provider, {
+		value = absSize,
+	}, React.createElement("frame", _attributes, children))
+end)
+return {
+	makeBoxProps = makeBoxProps,
+	Box = Box,
+}

package/out/primitives/Button.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Button.tsx — <button> equivalent for Roblox.
+ *
+ * Renders a <textbutton> with web-like style props.
+ * Delegates CSS→Roblox translation to webStyle(), and adds text-content
+ * manipulation features (textTransform, textDecoration, wordBreak) that
+ * require mutating the Text string before rendering.
+ * Typography mapping:
+ *   CSS Property        → Roblox Output
+ *   ─────────────────────────────────────────────────────────
+ *   fontSize            → TextSize (number)
+ *   fontFamily          → FontFace (Font object, defaults to BuilderSans)
+ *   fontWeight          → FontFace weight (normal/bold/black → Regular/Bold/Heavy)
+ *   textAlign           → TextXAlignment (left/center/right)
+ *   whiteSpace          → TextWrapped (nowrap → false, otherwise true)
+ *   color               → TextColor3 (Color3) + TextTransparency
+ *
+ * Event mapping:
+ *   React Prop          → Roblox Output
+ *   ─────────────────────────────────────────────────────────
+ *   onClick             → Event.Activated
+ *   onMouseEnter        → Event.MouseEnter
+ *   onMouseLeave        → Event.MouseLeave
+ *
+ * Maps to: HTML <button> → Roblox <textbutton>
+ *
+ * Usage:
+ *   <Button
+ *     style={{ backgroundColor: "#007BFF", padding: "10px 20px", color: "white", borderRadius: "4px" }}
+ *     onClick={() => print("Clicked!")}
+ *   >
+ *     Submit
+ *   </Button>
+ */
+import React from "@rbxts/react";
+import { CSSProperties } from "../styles/CSSTypes";
+import { DeepReadonly } from "../types";
+/**
+ * Branded ButtonProps — the `_buttonProps` brand ensures strict nominal typing.
+ * This prevents accidental bypasses or incorrect prop structures.
+ */
+export type ButtonProps = React.PropsWithChildren<React.ComponentProps<"textbutton">> & {
+    /**
+     * Web-like CSS styling object that automatically maps to Roblox properties
+     * and injects necessary UI constraints (UICorner, UIPadding, UIListLayout).
+     */
+    style?: CSSProperties;
+    onClick?: () => void;
+    onMouseEnter?: () => void;
+    onMouseLeave?: () => void;
+} & {
+    readonly _buttonProps?: unique symbol;
+};
+/** Helper to construct a branded ButtonProps. */
+export declare function makeButtonProps(props: Omit<ButtonProps, "_buttonProps">): DeepReadonly<ButtonProps>;
+/**
+ * Button component — The primary component for interactive clickable elements.
+ *
+ * Maps to: HTML <button> → Roblox <textbutton>
+ * Renders a native <textbutton>, mapping web styles and React-like event handlers (onClick, etc.).
+ */
+export declare const Button: React.ForwardRefExoticComponent<Omit<ButtonProps, "ref"> & React.RefAttributes<TextButton>>;