From 94c407787282429369bce37ce70c3bf2d13979d7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?0hm=E2=98=98=EF=B8=8F?= Date: Thu, 16 Jul 2026 00:27:18 +0530 Subject: [PATCH 1/2] docs: document differential pair constraints --- docs/elements/connector.mdx | 46 ++++++++ docs/elements/differential-pair.mdx | 160 ++++++++++++++++++++++++++++ docs/elements/trace.mdx | 24 +++-- 3 files changed, 222 insertions(+), 8 deletions(-) create mode 100644 docs/elements/differential-pair.mdx diff --git a/docs/elements/connector.mdx b/docs/elements/connector.mdx index 8a5a60d3..56c7f088 100644 --- a/docs/elements/connector.mdx +++ b/docs/elements/connector.mdx @@ -115,6 +115,52 @@ When a connector footprint is rendered, tscircuit computes `pcb_component.cable_ In the linked test, the computed cable insertion center is validated and then visualized as a small PCB note rectangle. +## Differential-pair pins + +A reusable connector component can return `` and +[``](./differential-pair.mdx) as siblings. The pair selects +the connector's labeled positive and negative pins, while the parent circuit +creates the actual traces. + +```tsx +import type { ConnectorProps } from "@tscircuit/props" + +export const UsbCConnector = ( + props: ConnectorProps & { readonly name: string }, +) => ( + <> + + .DP1`} + negativeConnection={`.${props.name} > .DM1`} + maxLengthSkew={0.05} + /> + +) + +export default () => ( + + + + + + + +) +``` + +The embedded pair uses pin selectors because the parent names the traces. Each +connection may instead be an exact trace name, such as `"usb_dp"` or +`"usb_dm"`. In either form, it must resolve to exactly one trace in the same +board or autorouted subcircuit. + ## Properties The TypeScript interface for `` is defined in [`@tscircuit/props`](https://github.com/tscircuit/props/blob/main/lib/components/connector.ts): diff --git a/docs/elements/differential-pair.mdx b/docs/elements/differential-pair.mdx new file mode 100644 index 00000000..d14dea06 --- /dev/null +++ b/docs/elements/differential-pair.mdx @@ -0,0 +1,160 @@ +--- +title: +description: Match the routed lengths of two traces within a maximum absolute difference. +--- + +import CircuitPreview from "@site/src/components/CircuitPreview" + +## Why use a differential pair? + +A differential signal, such as USB D+ and D-, travels over a positive and a +negative trace. If one route is longer than the other, the two halves of the +signal arrive at different times. + +`` tells a supported autorouter which two existing traces +form the pair and how much their routed lengths may differ. It does not create +electrical connections; add those with [``](./trace.mdx). + +This element currently constrains length matching only. It does not configure +differential impedance, trace width, pair spacing, or parallel routing. + +## Quick start with trace names + +Use trace names when the same circuit creates the traces and the constraint. +Give each `` a unique `name`, then reference those names from +``. + + ( + + + + + + + + + + ) +`} /> + +In this example: + +- `usb_dp` and `usb_dm` create the electrical connections. +- `` groups those connections for length matching. +- `maxLengthSkew={0.05}` allows an absolute routed-length difference of up to + 0.05 mm. + +Supported autorouters try to add length, often as a meander, to the shorter +route. Routing can fail when there is no valid segment or enough room to meet +the tolerance. + +## Choosing trace names or pin selectors + +| Use | When to choose it | Example | +| --- | --- | --- | +| Trace name | The same circuit defines and names the traces. | `positiveConnection="usb_dp"` | +| Pin selector | A reusable component knows its differential pins, while its parent creates the traces. | `positiveConnection=".USBC > .DP1"` | + +You may use a trace name for one connection and a pin selector for the other. +Each value must ultimately resolve to exactly one trace in the same board or +autorouted subcircuit. + +## Reusable connector component + +A reusable connector can declare the constraint using stable pin labels even +though it does not know what the parent circuit will name the traces. + +```tsx +import type { ConnectorProps } from "@tscircuit/props" + +export const UsbCConnector = ( + props: ConnectorProps & { readonly name: string }, +) => ( + <> + + .DP1`} + negativeConnection={`.${props.name} > .DM1`} + maxLengthSkew={0.05} + /> + +) + +export default () => ( + + + + + + + +) +``` + +The wrapper returns `` and `` as siblings. The +parent creates `usb_dp` and `usb_dm`; tscircuit finds those traces through the +connector's `DP1` and `DM1` pins. + +## How connections are resolved + +For each connection, tscircuit first looks for an exact trace `name`. If no +trace has that name, it treats the value as a pin/port selector. The result must +be exactly one trace in the differential pair's routing subcircuit. + +Connection values are not net names or component selectors. Use a trace name +such as `"usb_dp"`, or select a specific pin such as `".USBC > .DP1"`. + +## Troubleshooting + +- **Missing trace name:** Add a `` with the referenced `name`, or fix + the name in the differential pair. +- **Pin has no trace:** Create a trace connected to the selected pin. +- **Pin matches multiple traces:** Select a pin used by only one trace, or use + the intended trace's unique name. Branched traces make a pin ambiguous. +- **Component selector used:** `".USBC"` selects a component, not a pin. Use a + selector such as `".USBC > .DP1"`. +- **Different routing scope:** Keep the differential pair and both traces in + the same board or autorouted subcircuit. + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| `name` | `string` | Optional name for the differential pair. | +| `positiveConnection` | `string` | Exact positive trace name or pin/port selector. | +| `negativeConnection` | `string` | Exact negative trace name or pin/port selector. | +| `maxLengthSkew` | `number` | Maximum absolute difference between the routed lengths, in millimeters. Accepts `0` through `1`; defaults to `0.1` mm. | + diff --git a/docs/elements/trace.mdx b/docs/elements/trace.mdx index 985b0a85..4ab9ab2e 100644 --- a/docs/elements/trace.mdx +++ b/docs/elements/trace.mdx @@ -131,32 +131,40 @@ export default () => ( ## Differential Pairs -For high-speed signals, you often need pairs of traces to have matched lengths. You can use the `differentialPairKey` property to group traces: - -:::info -The `differentialPairKey` property is in beta and not available on all autorouters yet! -::: +For high-speed signals, use a [``](./differential-pair.mdx) +to identify two traces and constrain their routed-length skew. Connections can +refer to the traces by `name` or by a specific pin selector. ( + ) `} /> -The autorouter will ensure both traces in the pair have the same length. +The constraint is passed to the autorouter. Supported autorouters try to add +length to the shorter route until the absolute difference is at most +`maxLengthSkew`. This only constrains routed length; it does not set pair +spacing or differential impedance. See the dedicated page for pin selectors, +reusable connector components, and troubleshooting. ## Net vs Direct connections From 259c535aee9e97d7c620f356692000022fea7676 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?0hm=E2=98=98=EF=B8=8F?= Date: Thu, 16 Jul 2026 00:51:48 +0530 Subject: [PATCH 2/2] docs: address differential pair review --- docs/elements/connector.mdx | 46 -------------------- docs/elements/differential-pair.mdx | 65 ----------------------------- 2 files changed, 111 deletions(-) diff --git a/docs/elements/connector.mdx b/docs/elements/connector.mdx index 56c7f088..8a5a60d3 100644 --- a/docs/elements/connector.mdx +++ b/docs/elements/connector.mdx @@ -115,52 +115,6 @@ When a connector footprint is rendered, tscircuit computes `pcb_component.cable_ In the linked test, the computed cable insertion center is validated and then visualized as a small PCB note rectangle. -## Differential-pair pins - -A reusable connector component can return `` and -[``](./differential-pair.mdx) as siblings. The pair selects -the connector's labeled positive and negative pins, while the parent circuit -creates the actual traces. - -```tsx -import type { ConnectorProps } from "@tscircuit/props" - -export const UsbCConnector = ( - props: ConnectorProps & { readonly name: string }, -) => ( - <> - - .DP1`} - negativeConnection={`.${props.name} > .DM1`} - maxLengthSkew={0.05} - /> - -) - -export default () => ( - - - - - - - -) -``` - -The embedded pair uses pin selectors because the parent names the traces. Each -connection may instead be an exact trace name, such as `"usb_dp"` or -`"usb_dm"`. In either form, it must resolve to exactly one trace in the same -board or autorouted subcircuit. - ## Properties The TypeScript interface for `` is defined in [`@tscircuit/props`](https://github.com/tscircuit/props/blob/main/lib/components/connector.ts): diff --git a/docs/elements/differential-pair.mdx b/docs/elements/differential-pair.mdx index d14dea06..95d0fdd4 100644 --- a/docs/elements/differential-pair.mdx +++ b/docs/elements/differential-pair.mdx @@ -85,70 +85,6 @@ You may use a trace name for one connection and a pin selector for the other. Each value must ultimately resolve to exactly one trace in the same board or autorouted subcircuit. -## Reusable connector component - -A reusable connector can declare the constraint using stable pin labels even -though it does not know what the parent circuit will name the traces. - -```tsx -import type { ConnectorProps } from "@tscircuit/props" - -export const UsbCConnector = ( - props: ConnectorProps & { readonly name: string }, -) => ( - <> - - .DP1`} - negativeConnection={`.${props.name} > .DM1`} - maxLengthSkew={0.05} - /> - -) - -export default () => ( - - - - - - - -) -``` - -The wrapper returns `` and `` as siblings. The -parent creates `usb_dp` and `usb_dm`; tscircuit finds those traces through the -connector's `DP1` and `DM1` pins. - -## How connections are resolved - -For each connection, tscircuit first looks for an exact trace `name`. If no -trace has that name, it treats the value as a pin/port selector. The result must -be exactly one trace in the differential pair's routing subcircuit. - -Connection values are not net names or component selectors. Use a trace name -such as `"usb_dp"`, or select a specific pin such as `".USBC > .DP1"`. - -## Troubleshooting - -- **Missing trace name:** Add a `` with the referenced `name`, or fix - the name in the differential pair. -- **Pin has no trace:** Create a trace connected to the selected pin. -- **Pin matches multiple traces:** Select a pin used by only one trace, or use - the intended trace's unique name. Branched traces make a pin ambiguous. -- **Component selector used:** `".USBC"` selects a component, not a pin. Use a - selector such as `".USBC > .DP1"`. -- **Different routing scope:** Keep the differential pair and both traces in - the same board or autorouted subcircuit. - ## Properties | Property | Type | Description | @@ -157,4 +93,3 @@ such as `"usb_dp"`, or select a specific pin such as `".USBC > .DP1"`. | `positiveConnection` | `string` | Exact positive trace name or pin/port selector. | | `negativeConnection` | `string` | Exact negative trace name or pin/port selector. | | `maxLengthSkew` | `number` | Maximum absolute difference between the routed lengths, in millimeters. Accepts `0` through `1`; defaults to `0.1` mm. | -